Connect, draft, review and track a post

There are two ways in. Connect an assistant such as Claude or ChatGPT with no key at all, or mint a Credential and call the API yourself. Both end the same way: the agent drafts, and you approve the actual destination content.

Building against the API rather than through an assistant? The OpenAPI 3.1 description is at https://api.cometpost.app/v1/openapi.json (no key needed to fetch it), and the API contract is the prose version. MCP client setup is in the MCP README.

Connect from Claude or ChatGPT #

Sign in at the dashboard and connect a supported social account first; an assistant can only reach Channels that exist. Then add cometpost to the assistant by URL:

• Claude: Settings → Connectors → Add custom connector → https://mcp.cometpost.app/mcp
• ChatGPT: turn on developer mode, then add a connector with the same URL

The assistant sends you to Google to sign in, then to a consent page. Pick the Channels it may use (specific ones, or all including future ones) and leave Let it schedule posts without my approval off for this walkthrough, so it drafts. Ask the assistant to draft a post, then open the draft in the dashboard, review each destination and publish it. The assistant cannot approve its own draft.

Consent is remembered: reconnecting an assistant keeps the choices you made. To change its Channels or let it schedule, revoke it under Settings → Connected assistants and connect again. Revoking takes effect on the assistant's next request. The details are in OAuth agents.

Connect with a key #

For scripts, Claude Code, Cursor and anything else that can send a header. Sign in at the dashboard, connect a supported social account and create a Credential under New credential. Keep scheduling permission off for this walkthrough: the agent drafts, and you approve the actual destination content. Free media intake requires a connected account and an eligible free Workspace; otherwise choose a paid plan.

The following commands use curl and jq. Read the Credential without putting it in shell history (Bash):

read -r -s -p 'CometPost credential: ' COMETPOST_CREDENTIAL
export COMETPOST_CREDENTIAL
COMETPOST_API=https://api.cometpost.app
curl -fsS -H "Authorization: Bearer $COMETPOST_CREDENTIAL" "$COMETPOST_API/v1/platforms" | jq
curl -fsS -H "Authorization: Bearer $COMETPOST_CREDENTIAL" "$COMETPOST_API/v1/channels" | jq

Choose a connected Channel ID from that response. /v1/platforms tells you its caption limit, accepted media types/counts and Publish Options. For example, Instagram currently needs JPEG media; a text-only Threads post needs none.

For an image post, set a publicly reachable image URL you control. The API refuses private network addresses and checks what actually arrives:

read -r -p 'Channel ID: ' COMETPOST_CHANNEL
read -r -p 'Public image URL: ' COMETPOST_IMAGE
COMETPOST_MEDIA=$(curl -fsS -X POST \
  -H "Authorization: Bearer $COMETPOST_CREDENTIAL" -H 'Content-Type: application/json' \
  --data "$(jq -n --arg url "$COMETPOST_IMAGE" '{source_url:$url}')" \
  "$COMETPOST_API/v1/media" | jq -er '.id')

Alternatively, reuse an existing ready asset from GET /v1/media. Check its expiry before choosing a delivery time. For direct file upload, follow presign → PUT → complete; a presigned asset is not ready until completion succeeds.

Create a draft, supplying the exact camelCase API fields:

COMETPOST_POST=$(curl -fsS -X POST \
  -H "Authorization: Bearer $COMETPOST_CREDENTIAL" -H 'Content-Type: application/json' \
  --data "$(jq -n --arg channel "$COMETPOST_CHANNEL" --arg media "$COMETPOST_MEDIA" \
    '{body:"Shipping today.",channelIds:[$channel],mediaIds:[$media]}')" \
  "$COMETPOST_API/v1/posts" | jq -er '.id')
curl -fsS -H "Authorization: Bearer $COMETPOST_CREDENTIAL" \
  "$COMETPOST_API/v1/posts/$COMETPOST_POST" | jq

Open the draft in the dashboard. Review each destination's complete caption, ordered media, options and time; edit if needed, then publish. The Credential cannot approve its own draft. A draft changed after review must be reviewed again before release.

Track the result using the same GET command. Each Delivery reports its status, Attempts, failure reason and permalink when available. unscheduled means a workflow could not start, and can be re-armed using /schedule with scheduling permission or in the dashboard. delivered_to_drafts is a success that is not a post: the platform took a draft and the human finishes it in that app. Terminal failures have a separate human retry control; uncertain platform outcomes must be verified before retrying.

For automatic scheduling, deliberately mint a Credential with scheduling permission. Create then returns {post,deliveries} instead of the compact draft shape. Use scheduledFor with Z or an explicit offset; omit it for now. Send platform captions in variants and Channel-default overrides in publishOptions, as shown in the API contract.

For MCP with a key, or for the eleven tools, use the client setup. Capability/media discovery, creation and editing share the same authorization rules whether the bearer is a key or an assistant's OAuth token.