{"openapi":"3.1.0","info":{"title":"Surgemesh API","version":"1.0.0-beta","summary":"Agent-first social publishing with dynamic pricing.","description":"Schedule, publish, list and cancel social posts across brands and networks. One delivery = one post to one channel. Base $0.02 per delivery x a price multiplier (0.8x-3x) for the 15-minute slot. Quote first; price locks on accept. Errors are RFC 9457 problem+json with a `hint`. MCP: POST /mcp.","contact":{"url":"https://surgemesh.com"}},"servers":[{"url":"https://api.surgemesh.com"}],"externalDocs":{"url":"https://surgemesh.com/docs"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Agent key sm_... from POST /v1/signup or POST /v1/keys."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"UUID per logical action; reuse on retries. Same key + different body = 409."}},"responses":{"Problem":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Payment":{"description":"Payment required (x402) or insufficient credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"error":{"type":"string","description":"Stable machine code, e.g. insufficient_credit"},"field":{"type":"string"},"hint":{"type":"string","description":"What to do next"}}},"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"hint":{"type":"string"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string"},"resource":{"type":"string"},"description":{"type":"string"},"payTo":{"type":"string"},"asset":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"}}}}}},"Quote":{"type":"object","properties":{"slot":{"type":"string","format":"date-time"},"deliveries":{"type":"integer"},"multiplier":{"type":"number"},"price_usd":{"type":"number"},"price_micros":{"type":"integer"},"base_usd_per_delivery":{"type":"number"},"cheaper_slots":{"type":"array","items":{"type":"object","properties":{"slot":{"type":"string"},"multiplier":{"type":"number"},"price_usd":{"type":"number"}}}}}},"NewPost":{"type":"object","required":["brand_id","body","scheduled_at","channels"],"properties":{"brand_id":{"type":"string"},"body":{"type":"string","minLength":1,"maxLength":5000},"media_urls":{"type":"array","maxItems":10,"items":{"type":"string","format":"uri","description":"Public HTTPS only"}},"scheduled_at":{"type":"string","format":"date-time"},"channels":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string"}},"max_price_usd":{"type":"number","description":"Refuse (409 price_above_max) if dynamic pricing pushes the price above this"},"idempotency_key":{"type":"string","description":"Alternative to the Idempotency-Key header"}}},"PostAccepted":{"type":"object","properties":{"id":{"type":"string"},"gate_status":{"type":"string"},"sandbox":{"type":"boolean"},"slot":{"type":"string"},"multiplier":{"type":"number"},"price_usd":{"type":"number"},"free_deliveries_used":{"type":"integer"},"idempotent_replay":{"type":"boolean"}}},"Channel":{"type":"object","properties":{"id":{"type":"string"},"brand_id":{"type":"string"},"network":{"type":"string","enum":["facebook","instagram"]},"label":{"type":"string"},"connected":{"type":"boolean"},"active":{"type":"integer"}}}}},"paths":{"/v1/pricing":{"get":{"security":[],"operationId":"get_pricing","summary":"Prices, dynamic pricing rules and credit packs","responses":{"200":{"description":"Pricing"}}}},"/v1/quote":{"get":{"security":[],"operationId":"get_quote","summary":"Price quote for a slot (price locks when POST /v1/posts accepts the post; guard with max_price_usd)","parameters":[{"name":"scheduled_at","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"deliveries","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":1}}],"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/signup":{"post":{"security":[],"operationId":"signup","summary":"Create a sandbox account and get an API key (shown once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","accept_terms"],"properties":{"email":{"type":"string","format":"email"},"accept_terms":{"type":"boolean","const":true,"description":"Must be true: accepts https://surgemesh.com/terms and https://surgemesh.com/privacy"},"name":{"type":"string"},"brand":{"type":"string"}}}}}},"responses":{"201":{"description":"Account","content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string"},"plan":{"type":"string"},"brand_id":{"type":"string"},"api_key":{"type":"string"},"key_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/me":{"get":{"operationId":"get_me","summary":"Account, plan, credits, free deliveries left","responses":{"200":{"description":"Me"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/usage":{"get":{"operationId":"get_usage","summary":"Monthly usage and credit ledger","responses":{"200":{"description":"Usage"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/brands":{"get":{"operationId":"list_brands","summary":"List brands","responses":{"200":{"description":"Brands"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}},"post":{"operationId":"create_brand","summary":"Create a brand (admin)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Brand"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/channels":{"get":{"operationId":"list_channels","summary":"List channels","responses":{"200":{"description":"Channels","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}},"post":{"operationId":"connect_channel","summary":"Connect a Facebook Page or Instagram account (admin). Credentials encrypted, never returned.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["brand_id","network","credentials"],"properties":{"brand_id":{"type":"string"},"network":{"type":"string","enum":["facebook","instagram"]},"label":{"type":"string"},"credentials":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"page_id":{"type":"string","description":"facebook"},"ig_user_id":{"type":"string","description":"instagram"}}}}}}}},"responses":{"201":{"description":"Connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/channels/{id}":{"delete":{"operationId":"disconnect_channel","summary":"Disconnect and erase credentials (admin)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Disconnected"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/posts":{"post":{"operationId":"create_post","summary":"Schedule a post (price locks on accept)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewPost"}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostAccepted"}}}},"201":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostAccepted"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}},"get":{"operationId":"list_posts","summary":"Recent posts for a brand with per-channel state","parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Posts"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/posts/{id}":{"delete":{"operationId":"cancel_post","summary":"Cancel queued deliveries; refunds them to credit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/keys":{"get":{"operationId":"list_keys","summary":"List keys (admin)","responses":{"200":{"description":"Keys"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}},"post":{"operationId":"create_key","summary":"Mint a scoped key (admin), shown once","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write","admin"]}},"brands":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Key"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/keys/{id}":{"delete":{"operationId":"revoke_key","summary":"Revoke a key (admin)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/billing/topup":{"post":{"operationId":"topup","summary":"Buy a credit pack with x402 (USDC). First call returns 402 + requirements; retry with X-PAYMENT.","parameters":[{"name":"X-PAYMENT","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pack"],"properties":{"pack":{"type":"string","enum":["pack_5","pack_20","pack_100","5","20","100"]}}}}}},"responses":{"200":{"description":"Credited"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/Payment"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}}}},"/mcp":{"post":{"operationId":"mcp","summary":"MCP JSON-RPC 2.0 (initialize, tools/list, tools/call). Same Bearer key.","responses":{"200":{"description":"JSON-RPC response"}}}}}}