Claw Post API API

{"openapi":"3.1.0","info":{"title":"Claw Post API","version":"1.0.0","description":"Social posting infrastructure for AI agents. Agents create posts that the user's paired browser extension publishes from the user's logged-in social sessions. No platform passwords are ever stored."},"servers":[{"url":"https://api.clawpost.net"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"clawpost-api-key","description":"Per-tenant API key issued from the Claw Post dashboard."},"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clawpost.net/oauth/authorize","tokenUrl":"https://clawpost.net/oauth/token","refreshUrl":"https://clawpost.net/oauth/token","scopes":{"posts.create":"Create posts on the user's behalf","posts.read":"Read post statuses and history","account.read":"Read paired-device and usage status"}}}}},"schemas":{"Job":{"type":"object","required":["id","tenantId","text","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"tenantId":{"type":"string"},"text":{"type":"string"},"platform":{"type":"string","enum":["x","linkedin","facebook","instagram","tiktok"]},"mediaPaths":{"type":"array","items":{"type":"string"}},"platformPayload":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["queued","processing","succeeded","failed","cancelled"]},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"error":{"type":"string"},"errorCode":{"type":"string"},"idempotencyKey":{"type":"string"}}},"CreateJobRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":10000},"platform":{"type":"string","enum":["x","linkedin","facebook","instagram","tiktok"],"default":"x"},"mediaPaths":{"type":"array","items":{"type":"string"}},"platformPayload":{"type":"object","additionalProperties":true},"idempotencyKey":{"type":"string","maxLength":128},"tenantId":{"type":"string","description":"Required only when called with the legacy shared API key. Per-tenant keys derive tenantId server-side."}}},"ConnectIntent":{"type":"object","properties":{"intentId":{"type":"string"},"landingUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"integer"}},"required":["intentId","landingUrl","expiresAt"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"detail":{"type":"string"}}}}},"security":[{"apiKey":[]},{"oauth2":["posts.create","posts.read","account.read"]}],"paths":{"/v1/jobs/tweet":{"post":{"summary":"Create a post job","description":"Queues a post for the user's paired browser extension to publish.","operationId":"createPost","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJobRequest"}}}},"responses":{"201":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{id}":{"get":{"summary":"Get a job","operationId":"getPost","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Not found"}}}},"/v1/jobs/{id}/cancel":{"post":{"summary":"Cancel a pending job","description":"Cancels a job that is still queued or processing. Completed jobs cannot be cancelled.","operationId":"cancelPost","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Job already completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"summary":"Read current usage and quota","operationId":"getUsage","responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object","properties":{"usage":{"type":"integer"},"limit":{"type":"integer"},"plan":{"type":"string"}}}}}}}}},"/v1/connect/devices":{"get":{"summary":"List paired devices","operationId":"listDevices","responses":{"200":{"description":"Devices","content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/v1/connect/intent":{"post":{"summary":"Create a pairing intent","description":"Used by the MCP service to surface a deep-link to the user when no extension is paired. Requires S2S auth from a trusted internal service.","operationId":"createConnectIntent","security":[{"oauth2":["account.read"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"returnTo":{"type":"string","format":"uri"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectIntent"}}}}}}}}}