{ "openapi": "3.1.0", "info": { "title": "Posted HTTP API", "version": "0.2.0", "description": "All registered application, account, OAuth, MCP transport and health endpoints. Publishing and draft request schemas come from the shared runtime validators. Replace the example server with your installation. Documentation uses simple request examples and does not execute live publishing requests." }, "servers": [{ "url": "https://posted-api.example.com" }], "paths": { "/health/live": { "get": { "operationId": "get_health_live", "summary": "API liveness", "description": "Checks that the API process responds. It does not verify database readiness.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Health"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "example": { "status": "ok" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health/ready": { "get": { "operationId": "get_health_ready", "summary": "API readiness", "description": "Checks PostgreSQL connectivity and returns the running API version. An unavailable database returns HTTP 503.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Health"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": true }, "example": { "status": "ready", "version": "0.2.0" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/status": { "get": { "operationId": "get_api_auth_status", "summary": "Read installation status", "description": "Reports whether first-administrator setup is required and whether account email delivery is configured.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account and sessions"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "setupRequired": { "type": "boolean" }, "emailDeliveryConfigured": { "type": "boolean" } }, "additionalProperties": true }, "example": { "setupRequired": false, "emailDeliveryConfigured": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/setup": { "post": { "operationId": "post_api_auth_setup", "summary": "Create the first administrator", "description": "Requires the unused installation setup secret. Creates the team and verified first administrator, then sets a session cookie. A configured installation rejects another setup.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account and sessions"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "setupSecret": { "type": "string", "minLength": 1, "maxLength": 1024 }, "workspaceName": { "type": "string", "minLength": 1, "maxLength": 120 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 15, "maxLength": 1024 }, "dateFormat": { "type": "string", "enum": [ "day-short-month-year", "short-month-day-year", "year-month-day", "day-month-year", "month-day-year" ] }, "timeFormat": { "type": "string", "enum": [ "24-hour", "12-hour", "24-hour-seconds", "12-hour-seconds" ] }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "setupSecret", "workspaceName", "name", "email", "password" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "emailVerified": { "type": "boolean" }, "dateFormat": { "type": "string" }, "timeFormat": { "type": "string" }, "notificationPreferences": { "type": "object", "properties": { "assignments": { "type": "boolean" }, "mentions": { "type": "boolean" } }, "additionalProperties": true }, "passkeyCount": { "type": "integer" } }, "additionalProperties": true }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "user": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "admin", "timeZone": "UTC", "emailVerified": true, "dateFormat": "day-short-month-year", "timeFormat": "24-hour", "notificationPreferences": { "assignments": true, "mentions": true }, "passkeyCount": 0 }, "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/login": { "post": { "operationId": "post_api_auth_login", "summary": "Sign in with a password", "description": "Sets a session cookie after password verification, or returns requiresSecondFactor, challengeId, methods, preferredMethod and recoveryAvailable when a passkey is required.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account and sessions"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": ["email", "password"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "emailVerified": { "type": "boolean" }, "dateFormat": { "type": "string" }, "timeFormat": { "type": "string" }, "notificationPreferences": { "type": "object", "properties": { "assignments": { "type": "boolean" }, "mentions": { "type": "boolean" } }, "additionalProperties": true }, "passkeyCount": { "type": "integer" } }, "additionalProperties": true }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "user": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "member", "timeZone": "UTC", "emailVerified": true, "dateFormat": "day-short-month-year", "timeFormat": "24-hour", "notificationPreferences": { "assignments": true, "mentions": true }, "passkeyCount": 0 }, "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/reauth": { "post": { "operationId": "post_api_auth_reauth", "summary": "Verify a recent session", "description": "Reauthenticates the current session. A passkey-protected account receives a second-factor challenge before recent authentication is renewed.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Account and sessions"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": ["password"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/logout": { "post": { "operationId": "post_api_auth_logout", "summary": "Sign out", "description": "Deletes the supplied session if present and clears its cookie. Browser mutations carrying cookies require the trusted UI Origin.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account and sessions"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/me": { "get": { "operationId": "get_api_auth_me", "summary": "Read the signed-in account", "description": "Reads the current user, preferences and team. API keys and MCP credentials cannot impersonate this human session.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Account and sessions"], "security": [{ "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "emailVerified": { "type": "boolean" }, "dateFormat": { "type": "string" }, "timeFormat": { "type": "string" }, "notificationPreferences": { "type": "object", "properties": { "assignments": { "type": "boolean" }, "mentions": { "type": "boolean" } }, "additionalProperties": true }, "passkeyCount": { "type": "integer" } }, "additionalProperties": true }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "user": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "member", "timeZone": "UTC", "emailVerified": true, "dateFormat": "day-short-month-year", "timeFormat": "24-hour", "notificationPreferences": { "assignments": true, "mentions": true }, "passkeyCount": 0 }, "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/profile": { "patch": { "operationId": "patch_api_auth_profile", "summary": "Update account preferences", "description": "Changes only supplied profile fields and returns the updated identity.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Account and sessions"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100 }, "dateFormat": { "type": "string", "enum": [ "day-short-month-year", "short-month-day-year", "year-month-day", "day-month-year", "month-day-year" ] }, "timeFormat": { "type": "string", "enum": [ "24-hour", "12-hour", "24-hour-seconds", "12-hour-seconds" ] }, "notificationPreferences": { "type": "object", "properties": { "assignments": { "type": "boolean" }, "mentions": { "type": "boolean" } }, "required": ["assignments", "mentions"], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "emailVerified": { "type": "boolean" }, "dateFormat": { "type": "string" }, "timeFormat": { "type": "string" }, "notificationPreferences": { "type": "object", "properties": { "assignments": { "type": "boolean" }, "mentions": { "type": "boolean" } }, "additionalProperties": true }, "passkeyCount": { "type": "integer" } }, "additionalProperties": true }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "user": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "member", "timeZone": "UTC", "emailVerified": true, "dateFormat": "day-short-month-year", "timeFormat": "24-hour", "notificationPreferences": { "assignments": true, "mentions": true }, "passkeyCount": 0 }, "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/sessions": { "get": { "operationId": "get_api_auth_sessions", "summary": "List account sessions", "description": "Lists unexpired sessions belonging to the signed-in user, including whether each session is current.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Account and sessions"], "security": [{ "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userAgent": { "type": "string" }, "createdAt": { "type": "string" }, "lastSeenAt": { "type": "string" }, "expiresAt": { "type": "string" }, "current": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "items": [ { "id": "66666666-6666-4666-8666-666666666666", "userAgent": "Example browser", "createdAt": "2027-01-18T09:30:00.000Z", "lastSeenAt": "2027-01-18T09:30:00.000Z", "expiresAt": "2027-01-18T09:30:00.000Z", "current": true } ] } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/sessions/{id}": { "delete": { "operationId": "delete_api_auth_sessions_by_id", "summary": "Revoke an account session", "description": "Revokes an owned session. Revoking the current session also clears its cookie.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Account and sessions"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The id from the corresponding list, record or authorization response." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/password": { "post": { "operationId": "post_api_auth_password", "summary": "Change account password", "description": "Verifies the current password, replaces it, invalidates other sessions and revokes human-owned credentials and pending authorizations.\n\nA signed-in human session with recent authentication is required. Complete password/passkey reauthentication when requested.", "tags": ["Account and sessions"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 1024 }, "password": { "type": "string", "minLength": 15, "maxLength": 1024 } }, "required": ["currentPassword", "password"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/passkeys/recovery/verify": { "post": { "operationId": "post_api_auth_passkeys_recovery_verify", "summary": "Use a passkey recovery code", "description": "Consumes one recovery code against an active password-login challenge and creates a recovery-authenticated session.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Passkeys and recovery"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "code": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["challengeId", "code"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "emailVerified": { "type": "boolean" }, "dateFormat": { "type": "string" }, "timeFormat": { "type": "string" }, "notificationPreferences": { "type": "object", "properties": { "assignments": { "type": "boolean" }, "mentions": { "type": "boolean" } }, "additionalProperties": true }, "passkeyCount": { "type": "integer" } }, "additionalProperties": true }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "user": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "member", "timeZone": "UTC", "emailVerified": true, "dateFormat": "day-short-month-year", "timeFormat": "24-hour", "notificationPreferences": { "assignments": true, "mentions": true }, "passkeyCount": 0 }, "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/passkeys/recovery-codes": { "post": { "operationId": "post_api_auth_passkeys_recovery_codes", "summary": "Replace passkey recovery codes", "description": "Requires a passkey verification within the last ten minutes and an existing passkey. Returns newly generated one-time codes; retain them privately.\n\nA signed-in human session with recent authentication is required. Complete password/passkey reauthentication when requested.", "tags": ["Passkeys and recovery"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "example": { "recoveryCodes": ["example-one-time-code"] } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/passkeys": { "get": { "operationId": "get_api_auth_passkeys", "summary": "List passkeys", "description": "Lists the user's passkeys and remaining recovery-code count.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Passkeys and recovery"], "security": [{ "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "recoveryCodeCount": { "type": "integer" } }, "additionalProperties": true }, "example": { "items": [ { "id": "example-webauthn-credential-id", "name": "Studio laptop", "createdAt": "2027-01-18T09:30:00.000Z" } ], "recoveryCodeCount": 8 } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/passkeys/register/options": { "post": { "operationId": "post_api_auth_passkeys_register_options", "summary": "Begin passkey registration", "description": "Returns challengeId and WebAuthn creation options for a discoverable credential with user verification. At most twenty passkeys are allowed.\n\nA signed-in human session with recent authentication is required. Complete password/passkey reauthentication when requested.", "tags": ["Passkeys and recovery"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "options": { "type": "object", "properties": { "challenge": { "type": "string" }, "rp": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" } }, "additionalProperties": true }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" } }, "additionalProperties": true }, "pubKeyCredParams": { "type": "array", "items": { "type": "object", "properties": { "alg": { "type": "integer" }, "type": { "type": "string" } }, "additionalProperties": true } }, "timeout": { "type": "integer" }, "attestation": { "type": "string" }, "excludeCredentials": { "type": "array", "items": {} }, "authenticatorSelection": { "type": "object", "properties": { "residentKey": { "type": "string" }, "requireResidentKey": { "type": "boolean" }, "userVerification": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "challengeId": "example-challenge-token", "options": { "challenge": "example-browser-challenge", "rp": { "name": "Posted", "id": "posted.example.test" }, "user": { "id": "ZXhhbXBsZS11c2VyLWlk", "name": "alex@example.test", "displayName": "Alex Morgan" }, "pubKeyCredParams": [{ "alg": -7, "type": "public-key" }], "timeout": 60000, "attestation": "none", "excludeCredentials": [], "authenticatorSelection": { "residentKey": "required", "requireResidentKey": true, "userVerification": "required" } } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/passkeys/register/verify": { "post": { "operationId": "post_api_auth_passkeys_register_verify", "summary": "Complete passkey registration", "description": "Verifies the browser's RegistrationResponseJSON against the stored challenge, origin and RP ID. The first passkey also returns recoveryCodes.\n\nA signed-in human session with recent authentication is required. Complete password/passkey reauthentication when requested.", "tags": ["Passkeys and recovery"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "response": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "WebAuthn RegistrationResponseJSON from the browser" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": ["challengeId", "response", "name"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/passkeys/{id}": { "delete": { "operationId": "delete_api_auth_passkeys_by_id", "summary": "Remove a passkey", "description": "Removes an owned WebAuthn credential. Removing the last passkey also removes its recovery codes. The path ID is the credential ID, not a UUID.\n\nA signed-in human session with recent authentication is required. Complete password/passkey reauthentication when requested.", "tags": ["Passkeys and recovery"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id from the corresponding list, record or authorization response." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/passkeys/authenticate/options": { "post": { "operationId": "post_api_auth_passkeys_authenticate_options", "summary": "Begin passkey authentication", "description": "Returns challengeId and WebAuthn request options. Supply an active challengeId for password-login or reauthentication; a signed-in session without one starts reauthentication.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Passkeys and recovery"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "options": { "type": "object", "properties": { "challenge": { "type": "string" }, "rpId": { "type": "string" }, "userVerification": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "challengeId": "example-challenge-token", "options": { "challenge": "example-browser-challenge", "rpId": "posted.example.test", "userVerification": "required" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/passkeys/authenticate/verify": { "post": { "operationId": "post_api_auth_passkeys_authenticate_verify", "summary": "Complete passkey authentication", "description": "Verifies AuthenticationResponseJSON, consumes the challenge, and either creates a session or renews recent authentication.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Passkeys and recovery"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "response": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "WebAuthn AuthenticationResponseJSON from the browser" } }, "required": ["challengeId", "response"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "emailVerified": { "type": "boolean" }, "dateFormat": { "type": "string" }, "timeFormat": { "type": "string" }, "notificationPreferences": { "type": "object", "properties": { "assignments": { "type": "boolean" }, "mentions": { "type": "boolean" } }, "additionalProperties": true }, "passkeyCount": { "type": "integer" } }, "additionalProperties": true }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "user": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "member", "timeZone": "UTC", "emailVerified": true, "dateFormat": "day-short-month-year", "timeFormat": "24-hour", "notificationPreferences": { "assignments": true, "mentions": true }, "passkeyCount": 0 }, "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/recovery/reset": { "post": { "operationId": "post_api_auth_recovery_reset", "summary": "Reset a password with a recovery token", "description": "Consumes a valid email or operator recovery token and replaces the password. Existing sessions, human-owned credentials and pending authorizations are revoked. Operator recovery may also reset passkeys.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Passkeys and recovery"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "password": { "type": "string", "minLength": 15, "maxLength": 1024 } }, "required": ["token", "password"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/invitations": { "get": { "operationId": "get_api_auth_invitations", "summary": "List team invitations", "description": "Lists active invitations with cursor pagination. Use nextCursor unchanged; a cursor from another team is rejected.\n\nA signed-in human administrator is required. API keys and MCP credentials cannot replace that session. Sensitive operations can also require recent authentication.", "tags": ["Members and invitations"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "integer" }, { "name": "cursor", "in": "query", "required": false, "schema": { "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)$" }, "description": "uuid" } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": {} }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": ["string", "null"] } }, "additionalProperties": true }, "example": { "items": [], "hasMore": false, "nextCursor": null } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_api_auth_invitations", "summary": "Invite a team member", "description": "Creates an invitation and revokes older unused invitations for the same email. Returns its token and inviteUrl once, and queues email if SMTP is configured.\n\nA signed-in human administrator is required. API keys and MCP credentials cannot replace that session. Sensitive operations can also require recent authentication.", "tags": ["Members and invitations"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": ["admin", "member", "viewer"] } }, "required": ["email", "role"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitation": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" } }, "additionalProperties": true }, "token": { "type": "string" }, "inviteUrl": { "type": "string" }, "emailDelivery": { "type": "string" } }, "additionalProperties": true }, "example": { "invitation": { "id": "66666666-6666-4666-8666-666666666666", "email": "sam@example.test", "role": "member", "createdAt": "2027-01-18T09:30:00.000Z", "expiresAt": "2027-01-18T09:30:00.000Z" }, "token": "example-private-invitation-token", "inviteUrl": "https://posted.example.test/invite?token=example", "emailDelivery": "queued" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/invitations/{id}": { "delete": { "operationId": "delete_api_auth_invitations_by_id", "summary": "Revoke a team invitation", "description": "Revokes an active unused invitation. The original inviter must still have administrator authority.\n\nA signed-in human administrator is required. API keys and MCP credentials cannot replace that session. Sensitive operations can also require recent authentication.", "tags": ["Members and invitations"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The id from the corresponding list, record or authorization response." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/invitation": { "get": { "operationId": "get_api_auth_invitation", "summary": "Read an invitation", "description": "Looks up a valid invitation token without accepting it. Reports the team, invited email, role and whether email verification is required.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Members and invitations"], "security": [], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "string" } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitation": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string" }, "verificationRequired": { "type": "boolean" }, "workspaceName": { "type": "string" } }, "additionalProperties": true }, "verificationRequired": { "type": "boolean" } }, "additionalProperties": true }, "example": { "invitation": { "email": "sam@example.test", "role": "member", "verificationRequired": true, "workspaceName": "Studio team" }, "verificationRequired": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/accept-invitation": { "post": { "operationId": "post_api_auth_accept_invitation", "summary": "Accept a team invitation", "description": "Creates or reactivates the invited account and sets its session. Supply verificationToken when this invitation requires email verification.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Members and invitations"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "password": { "type": "string", "minLength": 15, "maxLength": 1024 }, "verificationToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": ["token", "name", "password"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "emailVerified": { "type": "boolean" }, "dateFormat": { "type": "string" }, "timeFormat": { "type": "string" }, "notificationPreferences": { "type": "object", "properties": { "assignments": { "type": "boolean" }, "mentions": { "type": "boolean" } }, "additionalProperties": true }, "passkeyCount": { "type": "integer" } }, "additionalProperties": true }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "user": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "member", "timeZone": "UTC", "emailVerified": true, "dateFormat": "day-short-month-year", "timeFormat": "24-hour", "notificationPreferences": { "assignments": true, "mentions": true }, "passkeyCount": 0 }, "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/members/{id}": { "patch": { "operationId": "patch_api_auth_members_by_id", "summary": "Change a member's role", "description": "Changes the current role while protecting the last active administrator. A role change revokes that human's MCP grants.\n\nA signed-in human administrator is required. API keys and MCP credentials cannot replace that session. Sensitive operations can also require recent authentication.", "tags": ["Members and invitations"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The id from the corresponding list, record or authorization response." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["admin", "member", "viewer"] } }, "required": ["role"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "passkeyEnabled": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "member": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "member", "timeZone": "UTC", "passkeyEnabled": false } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_api_auth_members_by_id", "summary": "Remove a team member", "description": "Disables the member and revokes their sessions, human-owned credentials and pending authorizations. The last administrator is protected.\n\nA signed-in human administrator is required. API keys and MCP credentials cannot replace that session. Sensitive operations can also require recent authentication.", "tags": ["Members and invitations"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The id from the corresponding list, record or authorization response." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/email-verification/request": { "post": { "operationId": "post_api_auth_email_verification_request", "summary": "Send account verification email", "description": "Queues verification for the signed-in account. Requires SMTP. resendAvailableAt is an epoch timestamp in milliseconds. X-Posted-User-Id can guard against a changed signed-in identity.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Account email"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "resendAvailableAt": { "type": "integer" } }, "additionalProperties": true }, "example": { "status": true, "resendAvailableAt": 1800264660000 } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/verification-email": { "post": { "operationId": "post_api_auth_verification_email", "summary": "Request verification email by address", "description": "Requests verification without disclosing whether the email is registered. Requires SMTP and is rate limited.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account email"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": ["email"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "additionalProperties": true }, "example": { "status": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/password-reset/request": { "post": { "operationId": "post_api_auth_password_reset_request", "summary": "Request a password-reset email", "description": "Queues a reset email for an eligible account and always returns a generic receipt. Requires SMTP.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account email"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": ["email"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "additionalProperties": true }, "example": { "status": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/email-verification/confirm": { "post": { "operationId": "post_api_auth_email_verification_confirm", "summary": "Confirm account email", "description": "Consumes the id and token from a valid verification link.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account email"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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)$" }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": ["id", "token"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/email-change": { "get": { "operationId": "get_api_auth_email_change", "summary": "Read pending email change", "description": "Returns the current pending email change or pending null.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Account email"], "security": [{ "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "object", "properties": { "email": { "type": "string" }, "expiresAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "pending": { "email": "new@example.test", "expiresAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_api_auth_email_change", "summary": "Request an email change", "description": "Queues verification to a new email address and returns the pending request. The email must be available and SMTP configured.\n\nA signed-in human session with recent authentication is required. Complete password/passkey reauthentication when requested.", "tags": ["Account email"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": ["email"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "object", "properties": { "email": { "type": "string" }, "expiresAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "pending": { "email": "new@example.test", "expiresAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_api_auth_email_change", "summary": "Cancel a pending email change", "description": "Cancels pending email changes and their unsent account emails.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Account email"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/email-change/confirm": { "post": { "operationId": "post_api_auth_email_change_confirm", "summary": "Confirm an email change", "description": "Consumes the link, verifies the new email, and revokes sessions and human-owned credentials. Sign in again afterward.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account email"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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)$" }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": ["id", "token"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "example": { "ok": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/invitation/verification/request": { "post": { "operationId": "post_api_auth_invitation_verification_request", "summary": "Send invitation verification code", "description": "Sends a six-digit code for an invitation requiring verification. Returns expiry and the earliest resend time.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account email"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": ["token"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "resendAvailableAt": { "type": "integer" }, "expiresAt": { "type": "string" } }, "additionalProperties": true }, "example": { "status": true, "resendAvailableAt": 1800264660000, "expiresAt": "2027-01-18T09:30:00.000Z" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/invitation/verification/confirm": { "post": { "operationId": "post_api_auth_invitation_verification_confirm", "summary": "Verify an invitation code", "description": "Checks the code and binds the returned verificationToken to the exact invited name. Supply that proof when accepting the invitation.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Account email"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": ["token", "name", "code"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verificationToken": { "type": "string" } }, "additionalProperties": true }, "example": { "verificationToken": "example-private-verification-token" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/posts/counts": { "get": { "operationId": "get_api_posts_counts", "summary": "Count scheduled posts and drafts", "description": "Returns team-wide group counts for the sidebar, independent of list pagination.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Posts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled": { "type": "integer" }, "drafts": { "type": "integer" } }, "additionalProperties": true }, "example": { "scheduled": 2, "drafts": 4 } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/media/config": { "get": { "operationId": "get_api_media_config", "summary": "Read media upload configuration", "description": "Reports whether private storage is enabled, supported MIME types and maximum upload sizes. Provider delivery limits can be lower.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Media"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxBytes": { "type": "integer" }, "maxImageBytes": { "type": "integer" }, "contentTypes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "example": { "enabled": true, "maxBytes": 104857600, "maxImageBytes": 20971520, "contentTypes": [ "image/jpeg", "image/png", "image/webp", "video/mp4", "video/quicktime" ] } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/social/connect/{provider}": { "post": { "operationId": "post_api_social_connect_by_provider", "summary": "Begin a social account connection", "description": "Creates OAuth state and PKCE material and returns the provider authorization URL. Bluesky requires a valid handle; complete authorization in the provider browser flow.\n\nAdministrator access with explicit administrator permission on API keys or MCP credentials, or a signed-in administrator.", "tags": ["Social connections"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": ["x", "threads", "linkedin", "bluesky"] }, "description": "The provider from the corresponding list, record or authorization response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "maxLength": 253 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorizationUrl": { "type": "string" } }, "additionalProperties": true }, "example": { "authorizationUrl": "https://provider.example.test/authorize?state=example" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/social/callback/{provider}": { "get": { "operationId": "get_api_social_callback_by_provider", "summary": "Complete a social OAuth callback", "description": "Provider callback handler. Verifies the stored state, verifier, initiating user and provider, saves encrypted tokens, then redirects to Posted. Do not fabricate callbacks or log authorization codes.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["Social connections"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": ["x", "threads", "linkedin", "bluesky"] }, "description": "The provider from the corresponding list, record or authorization response." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "string" }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" }, "description": "string" }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" }, "description": "string" }, { "name": "iss", "in": "query", "required": false, "schema": { "type": "string" }, "description": "string" } ], "responses": { "302": { "description": "Redirect to the authorization, consent or UI destination.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Redirect destination" } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/social/bluesky/client-metadata.json": { "get": { "operationId": "get_social_bluesky_client_metadata_json", "summary": "Read Bluesky client metadata", "description": "Serves the configured public OAuth client metadata. Returns 404 when Bluesky is not configured.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Social connections"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_name": { "type": "string" }, "application_type": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } }, "additionalProperties": true }, "example": { "client_id": "https://posted-api.example.test/social/bluesky/client-metadata.json", "client_name": "Posted", "application_type": "web", "token_endpoint_auth_method": "private_key_jwt" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/social/bluesky/jwks.json": { "get": { "operationId": "get_social_bluesky_jwks_json", "summary": "Read Bluesky public signing keys", "description": "Serves public signing keys only. The private P-256 signing key is never returned. Returns 404 when Bluesky is disabled.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["Social connections"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string" }, "crv": { "type": "string" }, "kid": { "type": "string" }, "x": { "type": "string" }, "y": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "keys": [ { "kty": "EC", "crv": "P-256", "kid": "posted-1", "x": "example-public-x", "y": "example-public-y" } ] } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/credentials": { "get": { "operationId": "get_api_credentials", "summary": "List personal API keys and MCP grants", "description": "Returns credential metadata without bearer secrets. Uses a UUID cursor and a maximum limit of 200.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["API key management"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "integer" }, { "name": "cursor", "in": "query", "required": false, "schema": { "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)$" }, "description": "uuid" } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": {} }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": ["string", "null"] } }, "additionalProperties": true }, "example": { "items": [], "hasMore": false, "nextCursor": null } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_api_credentials", "summary": "Create a personal API key", "description": "Requires recent authentication. Returns the new bearer secret once. Read access cannot mutate; includeAdmin requests administrative operations within the actor's authority.\n\nA signed-in human session with recent authentication is required. Complete password/passkey reauthentication when requested.", "tags": ["API key management"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "access": { "type": "string", "enum": ["read", "edit"] }, "includeAdmin": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "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))$" }, { "type": "null" } ] } }, "required": ["name", "access", "includeAdmin", "expiresAt"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "accessLevel": { "type": "string" }, "includeAdmin": { "type": "boolean" }, "tokenType": { "type": "string" }, "tokenPrefix": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": ["string", "null"] }, "revokedAt": { "type": ["string", "null"] } }, "additionalProperties": true }, "token": { "type": "string" } }, "additionalProperties": true }, "example": { "credential": { "id": "66666666-6666-4666-8666-666666666666", "name": "Studio assistant", "accessLevel": "read", "includeAdmin": false, "tokenType": "api-key", "tokenPrefix": "pst_example", "createdAt": "2027-01-18T09:30:00.000Z", "expiresAt": null, "revokedAt": null }, "token": "example-private-key-returned-once" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/credentials/{id}": { "delete": { "operationId": "delete_api_credentials_by_id", "summary": "Revoke a personal API key or MCP grant", "description": "Revokes an owned credential. Team revocation also requires recent authentication; subsequent requests cannot use the revoked key or grant.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["API key management"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The id from the corresponding list, record or authorization response." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "additionalProperties": true }, "example": { "revoked": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team-credentials": { "get": { "operationId": "get_api_team_credentials", "summary": "List team API keys and MCP grants", "description": "Returns credential metadata without bearer secrets. Uses a UUID cursor and a maximum limit of 200.\n\nA signed-in human administrator is required. API keys and MCP credentials cannot replace that session. Sensitive operations can also require recent authentication.", "tags": ["API key management"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "integer" }, { "name": "cursor", "in": "query", "required": false, "schema": { "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)$" }, "description": "uuid" } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": {} }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": ["string", "null"] } }, "additionalProperties": true }, "example": { "items": [], "hasMore": false, "nextCursor": null } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_api_team_credentials", "summary": "Create a team API key", "description": "Requires recent authentication. Returns the new bearer secret once. Read access cannot mutate; includeAdmin requests administrative operations within the actor's authority.\n\nA signed-in human administrator is required. API keys and MCP credentials cannot replace that session. Sensitive operations can also require recent authentication.", "tags": ["API key management"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "access": { "type": "string", "enum": ["read", "edit"] }, "includeAdmin": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "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))$" }, { "type": "null" } ] } }, "required": ["name", "access", "includeAdmin", "expiresAt"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "accessLevel": { "type": "string" }, "includeAdmin": { "type": "boolean" }, "tokenType": { "type": "string" }, "tokenPrefix": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": ["string", "null"] }, "revokedAt": { "type": ["string", "null"] } }, "additionalProperties": true }, "token": { "type": "string" } }, "additionalProperties": true }, "example": { "credential": { "id": "66666666-6666-4666-8666-666666666666", "name": "Studio assistant", "accessLevel": "read", "includeAdmin": false, "tokenType": "api-key", "tokenPrefix": "pst_example", "createdAt": "2027-01-18T09:30:00.000Z", "expiresAt": null, "revokedAt": null }, "token": "example-private-key-returned-once" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team-credentials/{id}": { "delete": { "operationId": "delete_api_team_credentials_by_id", "summary": "Revoke a team API key or MCP grant", "description": "Revokes an owned credential. Team revocation also requires recent authentication; subsequent requests cannot use the revoked key or grant.\n\nA signed-in human administrator is required. API keys and MCP credentials cannot replace that session. Sensitive operations can also require recent authentication.", "tags": ["API key management"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The id from the corresponding list, record or authorization response." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "additionalProperties": true }, "example": { "revoked": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "get_well_known_oauth_authorization_server", "summary": "OAuth authorization-server metadata", "description": "Advertises authorization, token, registration, revocation, S256 PKCE and user-selected read/write/admin capabilities.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["OAuth and MCP transport"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } }, "additionalProperties": true }, "example": { "issuer": "https://posted-api.example.test", "authorization_endpoint": "https://posted-api.example.test/oauth/authorize", "token_endpoint": "https://posted-api.example.test/oauth/token" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "get_well_known_oauth_protected_resource", "summary": "Protected-resource metadata", "description": "Advertises the MCP resource and its authorization server. HTTPS is required outside loopback development.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["OAuth and MCP transport"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } }, "resource_name": { "type": "string" } }, "additionalProperties": true }, "example": { "resource": "https://posted-api.example.test/mcp", "authorization_servers": ["https://posted-api.example.test"], "scopes_supported": ["read", "write", "admin"], "bearer_methods_supported": ["header"], "resource_name": "Posted MCP" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-protected-resource/mcp": { "get": { "operationId": "get_well_known_oauth_protected_resource_mcp", "summary": "MCP protected-resource metadata", "description": "Advertises the MCP resource and its authorization server. HTTPS is required outside loopback development.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["OAuth and MCP transport"], "security": [], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } }, "resource_name": { "type": "string" } }, "additionalProperties": true }, "example": { "resource": "https://posted-api.example.test/mcp", "authorization_servers": ["https://posted-api.example.test"], "scopes_supported": ["read", "write", "admin"], "bearer_methods_supported": ["header"], "resource_name": "Posted MCP" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/register": { "post": { "operationId": "post_oauth_register", "summary": "Register an OAuth client", "description": "Registers a client with validated redirect URIs. The returned client_secret is present only for a confidential client; retain it privately.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["OAuth and MCP transport"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_name": { "default": "MCP client", "type": "string", "minLength": 1, "maxLength": 120 }, "redirect_uris": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 2048 } }, "token_endpoint_auth_method": { "default": "client_secret_basic", "type": "string", "enum": [ "none", "client_secret_basic", "client_secret_post" ] }, "grant_types": { "default": ["authorization_code"], "minItems": 1, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": ["authorization_code", "refresh_token"] } }, "response_types": { "default": ["code"], "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "const": "code" } } }, "required": ["redirect_uris"] } } } }, "responses": { "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "type": "string" } }, "additionalProperties": true }, "example": { "client_id": "66666666-6666-4666-8666-666666666666", "client_name": "Studio assistant", "redirect_uris": ["https://client.example.test/callback"], "token_endpoint_auth_method": "none" } } } }, "default": { "description": "OAuth failure with error and error_description. Consent/session authority may also return the standard Posted error envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } } } } }, "/oauth/authorize": { "get": { "operationId": "get_oauth_authorize", "summary": "Begin MCP OAuth authorization", "description": "Validates the client, exact redirect URI, MCP resource and S256 PKCE challenge, then redirects to Posted's human consent flow. The human chooses the access level.\n\nNo signed-in session is required. Endpoint-specific tokens, setup secrets or challenges may still be required.", "tags": ["OAuth and MCP transport"], "security": [], "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "const": "code" }, "description": "string" }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "string" }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "uri" }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" }, "description": "string" }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "const": "S256" }, "description": "string" }, { "name": "resource", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "uri" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "string" }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" }, "description": "string" } ], "responses": { "302": { "description": "Redirect to the authorization, consent or UI destination.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Redirect destination" } } }, "default": { "description": "OAuth failure with error and error_description. Consent/session authority may also return the standard Posted error envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } } } } }, "/api/oauth/consent/{id}": { "get": { "operationId": "get_api_oauth_consent_by_id", "summary": "Read an MCP consent request", "description": "Reads the client and requested authorization for the signed-in human's approval screen.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["OAuth and MCP transport"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The id from the corresponding list, record or authorization response." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientName": { "type": "string" }, "clientId": { "type": "string" }, "clientTrust": { "type": "string" }, "redirectUri": { "type": "string" }, "scope": { "type": "string" }, "expiresIn": { "type": "integer" }, "user": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" } }, "additionalProperties": true }, "availableAccessLevels": { "type": "array", "items": { "type": "string" } }, "canApprove": { "type": "boolean" } }, "additionalProperties": true }, "example": { "clientName": "Studio assistant", "clientId": "example-client-id", "clientTrust": "unverified", "redirectUri": "https://client.example.test/callback", "scope": "read", "expiresIn": 2592000, "user": { "name": "Alex Morgan", "role": "member" }, "availableAccessLevels": ["read", "write"], "canApprove": true } } } }, "default": { "description": "OAuth failure with error and error_description. Consent/session authority may also return the standard Posted error envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } } } }, "post": { "operationId": "post_api_oauth_consent_by_id", "summary": "Approve or deny MCP consent", "description": "The human selects accessLevel. Approval requires recent authentication. When allow is false, omit accessLevel. A client cannot select or approve its own permissions.\n\nA signed-in human session is required. API keys and MCP bearer credentials cannot replace that session.", "tags": ["OAuth and MCP transport"], "security": [{ "sessionCookie": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The id from the corresponding list, record or authorization response." }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "The exact configured Posted UI origin. Required for browser mutations carrying session cookies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow": { "type": "boolean" }, "accessLevel": { "type": "string", "enum": ["read", "write", "admin"] } }, "required": ["allow"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectTo": { "type": "string" } }, "additionalProperties": true }, "example": { "redirectTo": "https://client.example.test/callback?code=example&state=example" } } } }, "default": { "description": "OAuth failure with error and error_description. Consent/session authority may also return the standard Posted error envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } } } } }, "/oauth/token": { "post": { "operationId": "post_oauth_token", "summary": "Exchange an OAuth authorization code", "description": "Uses an authorization code once with the original redirect URI, MCP resource and PKCE verifier. This server does not issue refresh tokens. Client authentication follows the registered method.\n\nAuthenticate the OAuth client using its registered method: none, client_secret_basic or client_secret_post. Client credentials are distinct from a user's API key.", "tags": ["OAuth and MCP transport"], "security": [{ "oauthClientBasic": [] }, {}], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "grant_type": { "type": "string", "const": "authorization_code" }, "code": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "code_verifier": { "type": "string" }, "resource": { "type": "string", "format": "uri" } }, "required": [ "grant_type", "code", "redirect_uri", "code_verifier", "resource" ] } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } }, "additionalProperties": true }, "example": { "access_token": "example-private-oauth-token", "token_type": "Bearer", "expires_in": 2592000, "scope": "read" } } } }, "default": { "description": "OAuth failure with error and error_description. Consent/session authority may also return the standard Posted error envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } } } } }, "/oauth/revoke": { "post": { "operationId": "post_oauth_revoke", "summary": "Revoke an OAuth token", "description": "Revokes a token for the authenticated OAuth client. A successful response has an empty body.\n\nAuthenticate the OAuth client using its registered method: none, client_secret_basic or client_secret_post. Client credentials are distinct from a user's API key.", "tags": ["OAuth and MCP transport"], "security": [{ "oauthClientBasic": [] }, {}], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "token": { "type": "string" }, "token_type_hint": { "type": "string" } }, "required": ["token"] } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record." }, "default": { "description": "OAuth failure with error and error_description. Consent/session authority may also return the standard Posted error envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } } } } }, "/mcp": { "post": { "operationId": "post_mcp", "summary": "Call the MCP transport", "description": "Streamable HTTP JSON-RPC endpoint. Use an MCP SDK for initialization, tools/list and tools/call. A static REST API key cannot authorize this transport.\n\nAn OAuth bearer token issued for this installation's MCP resource is required. Static REST API keys cannot access /mcp.", "tags": ["OAuth and MCP transport"], "security": [{ "mcpBearer": [] }], "parameters": [ { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string" }, "description": "application/json, text/event-stream" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": ["string", "number"] }, "method": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["jsonrpc", "method"] } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "id": { "type": "integer" }, "result": { "type": "object", "properties": { "tools": { "type": "array", "items": {} } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "jsonrpc": "2.0", "id": 1, "result": { "tools": [] } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "get_mcp", "summary": "MCP streaming request", "description": "The SDK accepts a GET with Accept: text/event-stream. Posted closes the per-request server after the response is created and does not provide a persistent event session. Use POST JSON-RPC for normal tool calls. Missing the SSE Accept type returns HTTP 406.\n\nAn OAuth bearer token issued for this installation's MCP resource is required. Static REST API keys cannot access /mcp.", "tags": ["OAuth and MCP transport"], "security": [{ "mcpBearer": [] }], "parameters": [ { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string" }, "description": "text/event-stream" } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_mcp", "summary": "MCP session termination request", "description": "Accepts transport termination with an empty HTTP 200 response. Posted allocates no persistent MCP session, so this does not revoke the OAuth grant. Revoke the grant in account settings or through the OAuth revocation endpoint.\n\nAn OAuth bearer token issued for this installation's MCP resource is required. Static REST API keys cannot access /mcp.", "tags": ["OAuth and MCP transport"], "security": [{ "mcpBearer": [] }], "parameters": [ { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string" }, "description": "application/json, text/event-stream" } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record." }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/drafts": { "get": { "operationId": "get_api_drafts", "summary": "List drafts", "description": "List team drafts. Drafts never enter the delivery queue.\n\nDrafts are team-owned and never enter the delivery queue. Pagination is numbered and pageSize is at most 100.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Drafts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "integer" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "integer" } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "textOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "connectionIds": { "type": "array", "items": { "type": "string" } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "accountId": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] }, "state": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "draftedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "additionalProperties": true }, "example": { "items": [ { "id": "33333333-3333-4333-8333-333333333333", "text": "An unfinished studio update.", "additionalPosts": [], "mediaOverrides": {}, "textOverrides": {}, "connectionIds": ["11111111-1111-4111-8111-111111111111"], "connections": [ { "id": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountId": "did:plc:example", "name": "Alex Morgan", "handle": "alex.example.test", "avatarUrl": null, "state": "connected", "createdAt": "2027-01-18T09:30:00.000Z" } ], "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "updatedAt": "2027-01-18T09:30:00.000Z", "draftedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null } } ], "total": 1, "page": 1, "pageSize": 20 } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/drafts/{draftId}": { "get": { "operationId": "get_api_drafts_by_draftId", "summary": "Get a draft", "description": "Read a draft's text, selected accounts, overrides and ordered media.\n\nResolved media and mediaOverrides contain media objects. Saving uses mediaIds and mediaOverrides containing IDs.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Drafts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The draftId from the corresponding list, record or authorization response." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "textOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "connectionIds": { "type": "array", "items": { "type": "string" } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "accountId": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] }, "state": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "draftedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "draft": { "id": "33333333-3333-4333-8333-333333333333", "text": "An unfinished studio update.", "additionalPosts": [], "mediaOverrides": {}, "textOverrides": {}, "connectionIds": ["11111111-1111-4111-8111-111111111111"], "connections": [ { "id": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountId": "did:plc:example", "name": "Alex Morgan", "handle": "alex.example.test", "avatarUrl": null, "state": "connected", "createdAt": "2027-01-18T09:30:00.000Z" } ], "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "updatedAt": "2027-01-18T09:30:00.000Z", "draftedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null } } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_api_drafts_by_draftId", "summary": "Save a draft", "description": "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.\n\nUse version 0 for a new UUID, or the latest version for an update. Reuse the same idempotencyKey and identical content when retrying. Incomplete content is allowed. Saving does not publish.\n\nWrite access: a member/administrator with a write-enabled credential, or an authorized signed-in user.", "tags": ["Drafts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The draftId from the corresponding list, record or authorization response." } ], "requestBody": { "required": true, "content": { "application/json": { "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 } }, "additionalPosts": { "default": [], "type": "array", "items": { "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 } }, "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)$" } }, "mediaOverrides": { "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": { "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)$" } } } }, "required": ["text", "mediaIds"], "additionalProperties": false } }, "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)$" } }, "mediaOverrides": { "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": { "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}$" } }, "required": [ "text", "connectionIds", "mediaIds", "version", "idempotencyKey" ], "additionalProperties": false }, "example": { "text": "An unfinished studio update.", "connectionIds": ["11111111-1111-4111-8111-111111111111"], "mediaIds": ["44444444-4444-4444-8444-444444444444"], "textOverrides": {}, "version": 0, "idempotencyKey": "studio-draft-2027-01-18" } } } }, "responses": { "200": { "description": "Existing operation replay or saved-draft update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "textOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "connectionIds": { "type": "array", "items": { "type": "string" } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "accountId": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] }, "state": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "draftedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "draft": { "id": "33333333-3333-4333-8333-333333333333", "text": "An unfinished studio update.", "additionalPosts": [], "mediaOverrides": {}, "textOverrides": {}, "connectionIds": ["11111111-1111-4111-8111-111111111111"], "connections": [ { "id": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountId": "did:plc:example", "name": "Alex Morgan", "handle": "alex.example.test", "avatarUrl": null, "state": "connected", "createdAt": "2027-01-18T09:30:00.000Z" } ], "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "updatedAt": "2027-01-18T09:30:00.000Z", "draftedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null } } } } } }, "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "textOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "connectionIds": { "type": "array", "items": { "type": "string" } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "accountId": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] }, "state": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "draftedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "draft": { "id": "33333333-3333-4333-8333-333333333333", "text": "An unfinished studio update.", "additionalPosts": [], "mediaOverrides": {}, "textOverrides": {}, "connectionIds": ["11111111-1111-4111-8111-111111111111"], "connections": [ { "id": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountId": "did:plc:example", "name": "Alex Morgan", "handle": "alex.example.test", "avatarUrl": null, "state": "connected", "createdAt": "2027-01-18T09:30:00.000Z" } ], "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "updatedAt": "2027-01-18T09:30:00.000Z", "draftedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null } } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_api_drafts_by_draftId", "summary": "Delete a draft", "description": "Delete a team draft using its current version. Ask the user before deleting their draft.\n\nDeletion removes the draft for the team. A stale version returns a conflict; read again before asking the user to confirm a new deletion.\n\nWrite access: a member/administrator with a write-enabled credential, or an authorized signed-in user.", "tags": ["Drafts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The draftId from the corresponding list, record or authorization response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["version"], "additionalProperties": false }, "example": { "version": 1 } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "completed": { "type": "boolean" } }, "additionalProperties": true }, "example": { "completed": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/connections": { "get": { "operationId": "get_api_connections", "summary": "List connections", "description": "List this team's connected social accounts. Credentials are never returned.\n\nCredentials are never returned. Each account includes connection attribution, last confirmed publication and its pending-delivery count.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Social connections"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "accountId": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] }, "state": { "type": "string" }, "createdAt": { "type": "string" }, "connectedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true }, "lastPublished": { "type": ["string", "null"] }, "scheduledCount": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountId": "did:plc:example", "name": "Alex Morgan", "handle": "alex.example.test", "avatarUrl": null, "state": "connected", "createdAt": "2027-01-18T09:30:00.000Z", "connectedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null }, "lastPublished": null, "scheduledCount": 1 } ] } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/providers": { "get": { "operationId": "get_api_providers", "summary": "List providers", "description": "Read enabled providers and their content limits.\n\nOnly fully configured providers appear. This returns Posted's enforced capabilities, not an assurance that a provider application has production approval.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Social connections"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "maxCharacters": { "type": "integer" }, "maxImages": { "type": "integer" }, "maxVideos": { "type": "integer" }, "maxVideoDurationSeconds": { "type": "integer" }, "maxImageBytes": { "type": "integer" }, "maxImageDimension": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "providers": [ { "id": "bluesky", "name": "Bluesky", "maxCharacters": 300, "maxImages": 4, "maxVideos": 1, "maxVideoDurationSeconds": 180, "maxImageBytes": 2000000, "maxImageDimension": 4000 } ] } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/media/uploads": { "post": { "operationId": "post_api_media_uploads", "summary": "Reserve a media upload", "description": "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.\n\nUse the returned uploadUrl and headers for the separate storage PUT. Reserving an upload does not create a post. Keep signed URLs private and use them before expiry.\n\nWrite access: a member/administrator with a write-enabled credential, or an authorized signed-in user.", "tags": ["Media"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "requestBody": { "required": true, "content": { "application/json": { "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"], "additionalProperties": false }, "example": { "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "alt": "A bright studio desk beside a window" } } } }, "responses": { "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mediaId": { "type": "string" }, "uploadUrl": { "type": "string" }, "headers": { "type": "object", "properties": { "Content-Type": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "mediaId": "44444444-4444-4444-8444-444444444444", "uploadUrl": "https://storage.example.test/signed-upload", "headers": { "Content-Type": "image/jpeg" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/media/{mediaId}/complete": { "post": { "operationId": "post_api_media_by_mediaId_complete", "summary": "Complete a media upload", "description": "Validate uploaded media and queue video preparation. Read its status until ready before scheduling it.\n\nImages can become ready immediately. Videos normally return state processing with HTTP 202 and must finish preparation before a post can use them. Invalid bytes or size are rejected.\n\nWrite access: a member/administrator with a write-enabled credential, or an authorized signed-in user.", "tags": ["Media"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The mediaId from the corresponding list, record or authorization response." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "media": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "state": "ready", "media": { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } } } } }, "202": { "description": "Video preparation is still processing; poll media status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "const": "processing" } } }, "example": { "state": "processing" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/media/{mediaId}/status": { "get": { "operationId": "get_api_media_by_mediaId_status", "summary": "Get media status", "description": "Read media preparation status and its metadata when ready.\n\nA processing result contains the state only. A ready result includes metadata. Failed video preparation returns an error instead of making media publishable.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Media"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The mediaId from the corresponding list, record or authorization response." } ], "responses": { "200": { "description": "Ready includes media metadata; uploading or processing returns only state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "media": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "state": "ready", "media": { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/media/{mediaId}/preview": { "get": { "operationId": "get_api_media_by_mediaId_preview", "summary": "Get a media preview", "description": "Get a short-lived private URL to view approved media.\n\nOnly approved, ready media from this team can be previewed. The URL is temporary and is not a permanent public attachment URL.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Media"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The mediaId from the corresponding list, record or authorization response." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "additionalProperties": true }, "example": { "url": "https://storage.example.test/signed-preview" } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/posts": { "get": { "operationId": "get_api_posts", "summary": "List posts", "description": "List scheduled posts or post history with per-account delivery states.\n\nScheduled includes groups with a scheduled, preparing or publishing delivery. History includes the remaining groups, including failed, uncertain and cancelled outcomes. It is not a list of confirmed publications alone.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Posts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": ["scheduled", "history"] }, "description": "scheduled, history" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "integer" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "integer" } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "scheduledAt": { "type": "string" }, "idempotencyKey": { "type": "string" }, "state": { "type": "string" }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "managedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "postIndex": { "type": "integer" }, "connectionId": { "type": "string" }, "provider": { "type": "string" }, "accountName": { "type": "string" }, "textOverride": { "type": ["string", "null"] }, "state": { "type": "string" }, "providerPostId": { "type": ["string", "null"] }, "publishedUrl": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "publishedAt": { "type": ["string", "null"] } }, "additionalProperties": true } } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "additionalProperties": true }, "example": { "items": [ { "id": "22222222-2222-4222-8222-222222222222", "text": "A small update from the studio.", "additionalPosts": [], "mediaOverrides": {}, "scheduledAt": "2027-01-18T09:30:00.000Z", "idempotencyKey": "studio-update-2027-01-18", "state": "scheduled", "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "managedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null }, "deliveries": [ { "id": "77777777-7777-4777-8777-777777777777", "postIndex": 0, "connectionId": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountName": "Alex Morgan", "textOverride": null, "state": "scheduled", "providerPostId": null, "publishedUrl": null, "error": null, "publishedAt": null } ] } ], "total": 1, "page": 1, "pageSize": 20 } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_api_posts", "summary": "Create a post", "description": "Schedule or publish a post for selected team accounts. Confirm content, accounts and time with the user. Reuse the same idempotencyKey for retries.\n\nA future scheduledAt schedules delivery. For immediate publication, use the current timestamp after the user's confirmation. Creation acknowledges a queued request, not confirmed provider publication. Use draftSource with its current version when converting a saved draft.\n\nWrite access: a member/administrator with a write-enabled credential, or an authorized signed-in user.", "tags": ["Posts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "requestBody": { "required": true, "content": { "application/json": { "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)$" } }, "mediaOverrides": { "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": { "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)$" } } }, "additionalPosts": { "default": [], "type": "array", "items": { "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 } }, "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)$" } }, "mediaOverrides": { "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": { "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)$" } } } }, "required": ["text", "mediaIds"], "additionalProperties": false } }, "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", "connectionIds", "mediaIds", "scheduledAt", "idempotencyKey" ], "additionalProperties": false }, "example": { "text": "A small update from the studio.", "connectionIds": ["11111111-1111-4111-8111-111111111111"], "mediaIds": ["44444444-4444-4444-8444-444444444444"], "scheduledAt": "2027-01-18T09:30:00.000Z", "idempotencyKey": "studio-update-2027-01-18" } } } }, "responses": { "200": { "description": "Existing operation replay or saved-draft update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "scheduledAt": { "type": "string" }, "idempotencyKey": { "type": "string" }, "state": { "type": "string" }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "managedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "postIndex": { "type": "integer" }, "connectionId": { "type": "string" }, "provider": { "type": "string" }, "accountName": { "type": "string" }, "textOverride": { "type": ["string", "null"] }, "state": { "type": "string" }, "providerPostId": { "type": ["string", "null"] }, "publishedUrl": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "publishedAt": { "type": ["string", "null"] } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "post": { "id": "22222222-2222-4222-8222-222222222222", "text": "A small update from the studio.", "additionalPosts": [], "mediaOverrides": {}, "scheduledAt": "2027-01-18T09:30:00.000Z", "idempotencyKey": "studio-update-2027-01-18", "state": "scheduled", "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "managedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null }, "deliveries": [ { "id": "77777777-7777-4777-8777-777777777777", "postIndex": 0, "connectionId": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountName": "Alex Morgan", "textOverride": null, "state": "scheduled", "providerPostId": null, "publishedUrl": null, "error": null, "publishedAt": null } ] } } } } }, "201": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "scheduledAt": { "type": "string" }, "idempotencyKey": { "type": "string" }, "state": { "type": "string" }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "managedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "postIndex": { "type": "integer" }, "connectionId": { "type": "string" }, "provider": { "type": "string" }, "accountName": { "type": "string" }, "textOverride": { "type": ["string", "null"] }, "state": { "type": "string" }, "providerPostId": { "type": ["string", "null"] }, "publishedUrl": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "publishedAt": { "type": ["string", "null"] } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "post": { "id": "22222222-2222-4222-8222-222222222222", "text": "A small update from the studio.", "additionalPosts": [], "mediaOverrides": {}, "scheduledAt": "2027-01-18T09:30:00.000Z", "idempotencyKey": "studio-update-2027-01-18", "state": "scheduled", "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "managedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null }, "deliveries": [ { "id": "77777777-7777-4777-8777-777777777777", "postIndex": 0, "connectionId": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountName": "Alex Morgan", "textOverride": null, "state": "scheduled", "providerPostId": null, "publishedUrl": null, "error": null, "publishedAt": null } ] } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/posts/{postId}": { "get": { "operationId": "get_api_posts_by_postId", "summary": "Get a post", "description": "Read a posting group, its media and individual account outcomes.\n\nThe root and additionalPosts represent the ordered sequence. deliveries contains a separate state for every account and postIndex. A group can be partial even if some posts were published.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Posts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The postId from the corresponding list, record or authorization response." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "scheduledAt": { "type": "string" }, "idempotencyKey": { "type": "string" }, "state": { "type": "string" }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "managedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "postIndex": { "type": "integer" }, "connectionId": { "type": "string" }, "provider": { "type": "string" }, "accountName": { "type": "string" }, "textOverride": { "type": ["string", "null"] }, "state": { "type": "string" }, "providerPostId": { "type": ["string", "null"] }, "publishedUrl": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "publishedAt": { "type": ["string", "null"] } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "post": { "id": "22222222-2222-4222-8222-222222222222", "text": "A small update from the studio.", "additionalPosts": [], "mediaOverrides": {}, "scheduledAt": "2027-01-18T09:30:00.000Z", "idempotencyKey": "studio-update-2027-01-18", "state": "scheduled", "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "managedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null }, "deliveries": [ { "id": "77777777-7777-4777-8777-777777777777", "postIndex": 0, "connectionId": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountName": "Alex Morgan", "textOverride": null, "state": "scheduled", "providerPostId": null, "publishedUrl": null, "error": null, "publishedAt": null } ] } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patch_api_posts_by_postId", "summary": "Update a scheduled post", "description": "Edit an entirely scheduled post using its current version. Publishing posts cannot be edited.\n\nOnly entirely scheduled groups can be edited. A stale version conflicts instead of overwriting a teammate's change. Changes apply to the complete sequence and its account overrides.\n\nWrite access: a member/administrator with a write-enabled credential, or an authorized signed-in user.", "tags": ["Posts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The postId from the corresponding list, record or authorization response." } ], "requestBody": { "required": true, "content": { "application/json": { "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)$" } }, "mediaOverrides": { "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": { "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)$" } } }, "additionalPosts": { "default": [], "type": "array", "items": { "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 } }, "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)$" } }, "mediaOverrides": { "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": { "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)$" } } } }, "required": ["text", "mediaIds"], "additionalProperties": false } }, "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 }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "text", "connectionIds", "mediaIds", "scheduledAt", "idempotencyKey", "version" ], "additionalProperties": false }, "example": { "text": "A small update from the studio.", "connectionIds": ["11111111-1111-4111-8111-111111111111"], "mediaIds": ["44444444-4444-4444-8444-444444444444"], "scheduledAt": "2027-01-18T09:30:00.000Z", "idempotencyKey": "studio-edit-2027-01-18", "version": 1 } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "scheduledAt": { "type": "string" }, "idempotencyKey": { "type": "string" }, "state": { "type": "string" }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "managedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "postIndex": { "type": "integer" }, "connectionId": { "type": "string" }, "provider": { "type": "string" }, "accountName": { "type": "string" }, "textOverride": { "type": ["string", "null"] }, "state": { "type": "string" }, "providerPostId": { "type": ["string", "null"] }, "publishedUrl": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "publishedAt": { "type": ["string", "null"] } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "post": { "id": "22222222-2222-4222-8222-222222222222", "text": "A small update from the studio.", "additionalPosts": [], "mediaOverrides": {}, "scheduledAt": "2027-01-18T09:30:00.000Z", "idempotencyKey": "studio-edit-2027-01-18", "state": "scheduled", "version": 2, "createdAt": "2027-01-18T09:30:00.000Z", "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "managedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null }, "deliveries": [ { "id": "77777777-7777-4777-8777-777777777777", "postIndex": 0, "connectionId": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountName": "Alex Morgan", "textOverride": null, "state": "scheduled", "providerPostId": null, "publishedUrl": null, "error": null, "publishedAt": null } ] } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_api_posts_by_postId", "summary": "Cancel a post", "description": "Cancel pending deliveries. Ask the user before cancelling their post. Published posts remain in history.\n\nCancellation stops pending deliveries. It does not remove provider-side publications, and a group with work already preparing or publishing cannot be cancelled safely.\n\nWrite access: a member/administrator with a write-enabled credential, or an authorized signed-in user.", "tags": ["Posts"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The postId from the corresponding list, record or authorization response." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "additionalPosts": { "type": "array", "items": {} }, "mediaOverrides": { "type": "object", "properties": {}, "additionalProperties": true }, "scheduledAt": { "type": "string" }, "idempotencyKey": { "type": "string" }, "state": { "type": "string" }, "version": { "type": "integer" }, "createdAt": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string" }, "durationSeconds": { "type": ["string", "null"] } }, "additionalProperties": true } }, "managedBy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": ["string", "null"] } }, "additionalProperties": true }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "postIndex": { "type": "integer" }, "connectionId": { "type": "string" }, "provider": { "type": "string" }, "accountName": { "type": "string" }, "textOverride": { "type": ["string", "null"] }, "state": { "type": "string" }, "providerPostId": { "type": ["string", "null"] }, "publishedUrl": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] }, "publishedAt": { "type": ["string", "null"] } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "post": { "id": "22222222-2222-4222-8222-222222222222", "text": "A small update from the studio.", "additionalPosts": [], "mediaOverrides": {}, "scheduledAt": "2027-01-18T09:30:00.000Z", "idempotencyKey": "studio-update-2027-01-18", "state": "cancelled", "version": 1, "createdAt": "2027-01-18T09:30:00.000Z", "media": [ { "id": "44444444-4444-4444-8444-444444444444", "fileName": "studio.jpg", "contentType": "image/jpeg", "sizeBytes": 245760, "width": 1600, "height": 900, "alt": "A bright studio desk beside a window", "durationSeconds": null } ], "managedBy": { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "avatarUrl": null }, "deliveries": [ { "id": "77777777-7777-4777-8777-777777777777", "postIndex": 0, "connectionId": "11111111-1111-4111-8111-111111111111", "provider": "bluesky", "accountName": "Alex Morgan", "textOverride": null, "state": "cancelled", "providerPostId": null, "publishedUrl": null, "error": null, "publishedAt": null } ] } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/connections/{connectionId}": { "delete": { "operationId": "delete_api_connections_by_connectionId", "summary": "Disconnect an account", "description": "Disconnect a team social account. Pending deliveries will fail. Ask the user before disconnecting.\n\nRequires Administrator access. Scheduled deliveries for this account fail after disconnection. Previously published provider posts remain in place.\n\nAdministrator access with explicit administrator permission on API keys or MCP credentials, or a signed-in administrator.", "tags": ["Social connections"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The connectionId from the corresponding list, record or authorization response." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "completed": { "type": "boolean" } }, "additionalProperties": true }, "example": { "completed": true } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspace": { "get": { "operationId": "get_api_workspace", "summary": "Get team settings", "description": "Read team settings.\n\nPosted has one team per installation. The wire response calls this object workspace.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Team"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patch_api_workspace", "summary": "Update team settings", "description": "Update the team name.\n\nRequires Administrator access. This changes the team name, not membership or provider ownership.\n\nAdministrator access with explicit administrator permission on API keys or MCP credentials, or a signed-in administrator.", "tags": ["Team"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": ["name"], "additionalProperties": false }, "example": { "name": "Studio team" } } } }, "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "workspace": { "id": "55555555-5555-4555-8555-555555555555", "name": "Studio team", "createdAt": "2027-01-18T09:30:00.000Z" } } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/members": { "get": { "operationId": "get_api_auth_members", "summary": "List members", "description": "List team members within the current access role.\n\nlimit is at most 1000. The REST endpoint also supports a cursor; the MCP tool currently accepts limit only. A changed member collection can return a conflict.\n\nRead access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.", "tags": ["Team"], "security": [{ "bearerAuth": [] }, { "sessionCookie": [] }], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "integer" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Opaque nextCursor from the preceding REST response. This parameter is not exposed by list_members." }, "description": "Opaque nextCursor from the preceding REST response. This parameter is not exposed by list_members." } ], "responses": { "200": { "description": "Successful response. Examples are illustrative; field values vary by record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "timeZone": { "type": "string" }, "passkeyEnabled": { "type": "boolean" } }, "additionalProperties": true } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": ["string", "null"] } }, "additionalProperties": true }, "example": { "items": [ { "id": "66666666-6666-4666-8666-666666666666", "name": "Alex Morgan", "email": "alex@example.test", "role": "member", "timeZone": "UTC", "passkeyEnabled": false } ], "hasMore": false, "nextCursor": null } } } }, "default": { "description": "Request failure. Inspect code, message and requestId; respect Retry-After on HTTP 429.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Personal or team Posted REST API key" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "posted_session", "description": "Signed-in human browser session; mutation requests also need the exact UI Origin" }, "mcpBearer": { "type": "http", "scheme": "bearer", "description": "OAuth bearer token issued for /mcp; REST API keys are not accepted" }, "oauthClientBasic": { "type": "http", "scheme": "basic", "description": "Registered OAuth client authentication, when client_secret_basic is selected" } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "requestId"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } } } } } } }