If you are an AI agent, start here

You can use Surgemesh to schedule, publish, list and cancel Facebook and Instagram posts for the brands you work for. Quote before you write, send an Idempotency-Key when you create a post, and when a response is an error, read its error code and follow its hint.

The short version

Read the spec at https://api.surgemesh.com/openapi.json, or connect to MCP at https://api.surgemesh.com/mcp.
Use the key your operator gave you, or call POST /v1/signup for a sandbox key.
Call GET /v1/me to learn your plan, scopes and brands.
Quote first: GET /v1/quote or the get_quote tool.
Create with an Idempotency-Key: POST /v1/posts or create_post with idempotency_key.
On any error, read error and hint and act on them.

Discover

llms.txt: https://surgemesh.com/llms.txt, with a full reference at https://surgemesh.com/llms-full.txt.
OpenAPI: https://api.surgemesh.com/openapi.json.
A2A agent card: https://api.surgemesh.com/.well-known/agent.json.
MCP: stateless JSON-RPC 2.0 at https://api.surgemesh.com/mcp. Call initialize (protocol version 2025-06-18), then tools/list.
Prices without a key: GET /v1/pricing and GET /v1/quote are public.

Authenticate

Send Authorization: Bearer sm_... on every authenticated REST request and on every HTTP request to /mcp.

curl https://api.surgemesh.com/v1/me \
  -H "Authorization: Bearer sm_..."

{
  "tenant_id": "t_...",
  "name": "Harbor Cafe",
  "plan": "live",
  "status": "active",
  "credit_usd": 21.94,
  "free_deliveries_left": 12,
  "month": "2026-11",
  "key": { "id": "<uuid>", "scopes": ["read", "write"], "brands": ["b_r7t2kq"] }
}

Stay inside your scopes and brands. If you get 403 insufficient_scope or 403 brand_not_allowed, do not try other keys you may have seen. Report the hint to your operator.

Quote before you write

Each delivery (one post to one channel) costs $0.02 times the multiplier of its 15-minute slot, from 0.8x to 3x. If your instructions allow timing flexibility and the quote's multiplier is above 1, compare price_usd with the entries in cheaper_slots (up to 3, within one hour) and pick the cheapest acceptable slot. Send max_price_usd with the post to refuse anything above your budget; the price is locked on acceptance.

Use an idempotency key when creating posts

Generate a new UUID for each logical action, such as "publish this announcement", and send it as the Idempotency-Key header on POST /v1/posts (or as idempotency_key in create_post). Reuse that key for every retry of that action. The same key and body return the original result with "idempotent_replay": true; a changed body returns 409 idempotency_key_reused. Cancels, key changes and top-ups do not need a key.

Handle 402 and payment errors

A 402 insufficient_credit means the account cannot pay for the post, and nothing was created.

During the beta: payments are not enabled. The 402 is a problem+json error with a quote, and POST /v1/billing/topup returns 503 payments_not_enabled. Stop and tell your operator; do not loop.
When payments are enabled: the 402 body is an x402 offer for pack_5 whose resource is the top-up endpoint. If you have a wallet and permission to spend, pay via POST /v1/billing/topup with an X-PAYMENT header, then retry the post with its original Idempotency-Key. If you do not, report the hint to your operator.

Retry rules

429 rate_limited: wait the seconds in Retry-After, then retry with the same Idempotency-Key.
429 sandbox_limit: the sandbox's 100 posts per month are used. Retrying will not help; tell your operator.
500 internal_error or a network timeout: retry with exponential backoff and the same Idempotency-Key. Include request_id when reporting.
409 price_above_max: requote and pick a cheaper slot, or ask before raising max_price_usd.
Other 4xx and 503: do not retry unchanged. Read hint, fix the request or escalate.

Read the hint field

Every error is application/problem+json with an error code and a hint written for you:

{
  "type": "https://surgemesh.com/errors/invalid-field",
  "title": "Invalid field",
  "status": 400,
  "detail": "Invalid field: scheduled_at",
  "error": "invalid_field",
  "field": "scheduled_at",
  "hint": "Fix the field named in `field` and retry. Schemas: GET /openapi.json."
}

Over MCP, the same JSON arrives in content[0].text with isError: true.

Cancel when plans change

If you are told to stop a scheduled post, call DELETE /v1/posts/{id} or the cancel_post tool. Queued deliveries are cancelled and refunded, and the response reports refunded_usd. If nothing is still queued, you get 409 post_not_cancelable.