REST and MCP publishing reference

REST clients use a personal or team API key in the Authorization header. Browser sessions use cookies and exact-origin checks. MCP uses OAuth at the API origin’s /mcp endpoint. Every operation checks the current actor’s permission.

Requests, versions and retries

Posting and saving a draft use a content-bound idempotencyKey. Reuse one key across retries of the same logical request; use a new key for an intentional new operation. A key reused for different content conflicts. Edits use the latest version; a stale version conflicts. Draft publication supplies draftSource with its ID and current version so conversion happens once. A post’s scheduledAt is an ISO 8601 timestamp with an offset. A future timestamp schedules delivery; an immediate timestamp requests immediate delivery. A created response records the request, not confirmed provider publication. Inspect deliveries afterward. Text overrides are keyed by selected connection IDs. Media uploads return signed URLs; PUT bytes using the supplied headers, complete the upload, then poll status until ready. Post and draft bodies use mediaIds, and responses use media.

Operation catalogue

This catalogue is generated from the same tool definitions used by MCP. Path parameters are supplied separately in REST; for MCP they are part of the tool input. HTTP permissions still apply to API keys and browser sessions. A successful create usually returns 201; replay/update returns 200; processing media returns 202. Validation, authentication, permission, missing-record and conflict failures use 400, 401, 403, 404 and 409 respectively. Media failure uses 422.

Tool	HTTP	Path	Access
`list_drafts`	GET	`/api/drafts`	Read
`get_draft`	GET	`/api/drafts/:draftId`	Read
`save_draft`	POST	`/api/drafts/:draftId`	Write
`delete_draft`	DELETE	`/api/drafts/:draftId`	Write
`list_connections`	GET	`/api/connections`	Read
`list_providers`	GET	`/api/providers`	Read
`reserve_media_upload`	POST	`/api/media/uploads`	Write
`complete_media_upload`	POST	`/api/media/:mediaId/complete`	Write
`get_media_status`	GET	`/api/media/:mediaId/status`	Read
`get_media_preview`	GET	`/api/media/:mediaId/preview`	Read
`list_posts`	GET	`/api/posts`	Read
`get_post`	GET	`/api/posts/:postId`	Read
`create_post`	POST	`/api/posts`	Write
`update_post`	PATCH	`/api/posts/:postId`	Write
`cancel_post`	DELETE	`/api/posts/:postId`	Write
`disconnect_account`	DELETE	`/api/connections/:connectionId`	Administrator
`get_team`	GET	`/api/workspace`	Read
`update_team`	PATCH	`/api/workspace`	Administrator
`list_members`	GET	`/api/auth/members`	Read

Input schemas

Schemas below describe MCP inputs. Refinements such as team ownership, selected-account membership, provider content limits and version/idempotency rules are also enforced by the shared HTTP handlers.

list_drafts

List team drafts. Drafts never enter the delivery queue.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "additionalProperties": false
}

get_draft

Read a draft’s text, selected accounts, overrides and ordered media.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "draftId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": ["draftId"],
  "additionalProperties": false
}

save_draft

Save incomplete content without publishing. Use version 0 and a new draftId for a new draft, or its current version to update. Reuse the request key for retries.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 64000
    },
    "textOverrides": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 64000
      }
    },
    "connectionIds": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "mediaIds": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "version": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotencyKey": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{8,128}$"
    },
    "draftId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "text",
    "textOverrides",
    "connectionIds",
    "mediaIds",
    "version",
    "idempotencyKey",
    "draftId"
  ],
  "additionalProperties": false
}

delete_draft

Delete a team draft using its current version. Ask the user before deleting their draft.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "draftId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": ["draftId", "version"],
  "additionalProperties": false
}

list_connections

List this team’s connected social accounts. Credentials are never returned.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_providers

Read enabled providers and their content limits.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

reserve_media_upload

Reserve a private image or video upload. PUT the approved file to the returned URL using its headers, then complete the upload. No post is created.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "fileName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "contentType": {
      "type": "string",
      "enum": [
        "image/jpeg",
        "image/png",
        "image/webp",
        "video/mp4",
        "video/quicktime"
      ]
    },
    "sizeBytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "alt": {
      "default": "",
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": ["fileName", "contentType", "sizeBytes", "alt"],
  "additionalProperties": false
}

complete_media_upload

Validate uploaded media and queue video preparation. Read its status until ready before scheduling it.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mediaId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": ["mediaId"],
  "additionalProperties": false
}

get_media_status

Read media preparation status and its metadata when ready.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mediaId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": ["mediaId"],
  "additionalProperties": false
}

get_media_preview

Get a short-lived private URL to view approved media.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mediaId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": ["mediaId"],
  "additionalProperties": false
}

list_posts

List scheduled posts or post history with per-account delivery states.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "view": {
      "type": "string",
      "enum": ["scheduled", "history"]
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "additionalProperties": false
}

get_post

Read a posting group, its media and individual account outcomes.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": ["postId"],
  "additionalProperties": false
}

create_post

Schedule or publish a post for selected team accounts. Confirm content, accounts and time with the user. Reuse the same idempotencyKey for retries.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 3000
    },
    "textOverrides": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 3000
      }
    },
    "connectionIds": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "mediaIds": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "scheduledAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
    },
    "idempotencyKey": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{8,128}$"
    },
    "draftSource": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "version": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": ["id", "version"],
      "additionalProperties": false
    }
  },
  "required": [
    "text",
    "textOverrides",
    "connectionIds",
    "mediaIds",
    "scheduledAt",
    "idempotencyKey"
  ],
  "additionalProperties": false
}

update_post

Edit an entirely scheduled post using its current version. Publishing posts cannot be edited.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 3000
    },
    "textOverrides": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 3000
      }
    },
    "connectionIds": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "mediaIds": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "scheduledAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
    },
    "idempotencyKey": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{8,128}$"
    },
    "draftSource": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "version": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": ["id", "version"],
      "additionalProperties": false
    },
    "postId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "text",
    "textOverrides",
    "connectionIds",
    "mediaIds",
    "scheduledAt",
    "idempotencyKey",
    "postId",
    "version"
  ],
  "additionalProperties": false
}

cancel_post

Cancel pending deliveries. Ask the user before cancelling their post. Published posts remain in history.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": ["postId"],
  "additionalProperties": false
}

disconnect_account

Disconnect a team social account. Pending deliveries will fail. Ask the user before disconnecting.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "connectionId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": ["connectionId"],
  "additionalProperties": false
}

get_team

Read team settings.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

update_team

Update the team name.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    }
  },
  "required": ["name"],
  "additionalProperties": false
}

list_members

List team members within the current access role.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "additionalProperties": false
}

​Requests, versions and retries

​Operation catalogue

​Input schemas

​list_drafts

​get_draft

​save_draft

​delete_draft

​list_connections

​list_providers

​reserve_media_upload

​complete_media_upload

​get_media_status

​get_media_preview

​list_posts

​get_post

​create_post

​update_post

​cancel_post

​disconnect_account

​get_team

​update_team

​list_members