CoPost API Reference

Authentication

Every /v1 request — and every MCP call — is authenticated with an API key tied to your CoPost account. There is no session or cookie auth on this surface.

curl https://api.copost.io/v1/me \
  -H "x-api-key: YOUR_API_KEY"

The key is sent as a raw header value, hashed with SHA-256, and matched against a stored key record — the plaintext key is never persisted server-side, so treat it like a password: it isn't recoverable if lost, only reissuable.

Conventions

A handful of shapes repeat across the whole surface.

Response envelope

Every response, success or failure, is a JSON object with a success boolean.

{
  "success": true,
  "data": { "...": "..." }
}

{
  "success": false,
  "message": "caption is required"
}

Pagination

List endpoints that can grow unbounded accept page and limit query params and wrap their array in a paging envelope instead of nesting it under plain data:

{
  "data": [ "...": "..." ],
  "page": 1,
  "limit": 20,
  "total": 57,
  "hasMore": true
}

Status codes

Account

A single endpoint to identify the caller and see which brand spaces they can reach.

{
  "success": true,
  "data": {
    "userId": "65b02c4a57e8884025d342c6",
    "userEmail": "[email protected]",
    "fullName": "Karl Fountain",
    "userName": "karlf",
    "subscriptionType": "teams",
    "zonesOwned": [
      { "zoneId": "20b63826-aa94-4b63-839a-f99c4d23bceb", "name": "CoPost", "asUser": false, "logo": null, "deleted": false }
    ],
    "zonesMemberOf": []
  }
}

Brand Spaces

A brand space (internally a zone) is the workspace that holds connected social accounts, labels, post slots, and posts. Almost every other route hangs off a zoneId.

{
  "data": [
    {
      "zoneId": "20b63826-aa94-4b63-839a-f99c4d23bceb",
      "name": "CoPost",
      "owner": { "userId": "65b02c4a57e8884025d342c6", "fullName": "Karl Fountain" },
      "subscriptionType": "teams",
      "createdAt": 1735689600000,
      "lastUpdated": 1787890549122
    }
  ],
  "page": 1, "limit": 20, "total": 1, "hasMore": false
}

Posts

Posts are the core resource: one piece of content, optionally split into per-platform variants, targeted at one or more connected accounts. Both list and read return the Post shape — a shared content block plus a platforms array, not the raw internal document.

{
  "data": [ { "key": "f1527cc9-...", "content": { "...": "see Post model" }, "platforms": [ "..." ] } ],
  "page": 1, "limit": 1, "total": 12, "hasMore": true
}

Media

Post responses only ever embed { objectKey, signedUrl } for images and video — enough to render them, not enough to bloat a list response. Resolve the rest on demand here.

{
  "success": true,
  "data": [
    {
      "objectKey": "20b63826-.../image/669dc810-...",
      "signedUrl": "https://....s3.amazonaws.com/...&Signature=...",
      "originalFileName": "Your_Voice,_Amplified",
      "extension": "webp",
      "resolution": "928 x 1152",
      "width": 928, "height": 1152, "pixels": 1069056,
      "size": 119622,
      "type": "image/webp",
      "endpoint": "image",
      "thumbSmallObjectKey": "20b63826-.../image/669dc810-...-thumb-small",
      "thumbMediumObjectKey": "20b63826-.../image/669dc810-...-thumb-medium",
      "tags": [], "labels": [], "altText": "", "caption": "",
      "createdAt": 1787890549106
    }
  ]
}

Labels & Post Slot Collections

Labels are simple tags for organizing posts. Post slot collections are recurring publishing queues — give a post a slotId instead of a scheduledDate and it drops into the slot's next open time.

Data Models

The shapes referenced throughout the endpoints above.

MCP Server

The same service layer is exposed as an MCP server, so any MCP-capable client — Claude, an agent framework, your own tool-calling loop — can drive CoPost directly. It speaks Streamable HTTP at a single endpoint.

Connecting

Two ways in, both landing on the same tool set:

curl https://mcp.copost.io/mcp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OAuth flow

Clients that support MCP's OAuth discovery find everything they need at:

1. Register

   POST /mcp/oauth/register with redirect_uris (must be https://) & client_name → back comes a client_id. No secret; this is a public-client flow.

2. Authorize

   GET /mcp/oauth/authorize with response_type=code, client_id, redirect_uri, a PKCE code_challenge (S256), and state → redirects the user to CoPost's consent screen.

3. Consent

   The user approves in-app. CoPost redirects back to your redirect_uri with a short-lived code.

4. Exchange

   POST /mcp/oauth/token with grant_type=authorization_code, the code, and your code_verifier → a Bearer access_token (1 hour) and refresh_token.

5. Call

   Send Authorization: Bearer <access_token> to /mcp. Refresh with grant_type=refresh_token once it expires — each refresh rotates both tokens.

Tool catalog

13 tools, one MCP server per authenticated user. Every tool that touches a brand space checks membership the same way the REST middleware does — a zoneId you don't belong to throws, it doesn't leak data.

REST parity notes

The two surfaces share one service layer, so behavior matches almost everywhere. The exceptions:

Build your first post

End to end, over REST: find a brand space, attach an image, publish it.

1. Find your zoneId

   curl

   curl https://api.copost.io/v1/me -H "x-api-key: YOUR_API_KEY"
   # -> data.zonesOwned[0].zoneId

2. Check which accounts are connected

   curl

   curl https://api.copost.io/v1/brand-spaces/ZONE_ID \
     -H "x-api-key: YOUR_API_KEY"
   # -> data.socials[].{ id, user.id }

3. Upload an image

   curl

   curl -X POST https://api.copost.io/v1/brand-spaces/ZONE_ID/media \
     -H "x-api-key: YOUR_API_KEY" \
     -F "file=@./trailhead.jpg"
   # -> data.objectKey

4. Create the post

   curl

   curl -X POST https://api.copost.io/v1/brand-spaces/ZONE_ID/posts \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "caption": "New trailheads just opened south of the ridge",
       "scheduledDate": 1788080400000,
       "objectKeys": ["ZONE_ID/image/OBJECT_ID"],
       "platforms": [{ "social": "instagram" }, { "social": "facebook" }]
     }'

5. Confirm it

   curl

   curl https://api.copost.io/v1/brand-spaces/ZONE_ID/posts/POST_KEY \
     -H "x-api-key: YOUR_API_KEY"