{ "openapi": "3.1.0", "info": { "title": "OneSocial API", "version": "1.0.0", "summary": "Schedule and publish social posts across Bluesky, Telegram, Discord, and Mastodon, plus analytics, inbox, contacts, broadcasts, sequences, automations, and a paid Ads Manager across Meta, Google, TikTok, LinkedIn, Pinterest, and X.", "description": "One REST API (and a parity MCP server at /api/mcp) to connect social accounts, schedule/publish posts, track analytics, manage a unified inbox (comments/mentions/reviews/DMs), maintain a contacts CRM with custom fields, run broadcasts/sequences/comment-to-DM automations, and run a paid Ads Manager (ad accounts, campaigns, ads, audiences, tracking tags) across Meta, Google, TikTok, LinkedIn, Pinterest, and X. All endpoints are versioned under /api/v1 (except the D1 media file server at /api/v1/media/file/{tenantId}/{filename}, which is a plain unauthenticated static-file GET), authenticate via an `sk_`-prefixed API key as an HTTP Bearer token, and respond with the envelope `{ data }` for single resources or `{ data, page, limit, total }` for lists. Errors are `{ error: { code, message } }` with a matching HTTP status. Scopes are a closed allowlist (see `@/lib/scopes`): a key needs the exact scope string for an action (or `*`/`admin` for full access) — an empty scopes array grants nothing. A handful of read endpoints (comments, mentions, reviews, broadcasts, sequences, automations lists) do not yet enforce their `:read` scope — any authenticated key can call them; this is called out per-operation below. Ad-network credentials are entirely optional server-side config (`_ADS_*` env vars); every Ads Manager endpoint is fully exercisable with zero ad-network credentials configured — unconfigured live calls fail closed and the local DB state is persisted regardless (see the AdAccounts/Ads/AdCampaigns/AdAudiences/TrackingTags operations below for specifics).", "license": { "name": "Proprietary" } }, "servers": [ { "url": "/api", "description": "Relative to whichever origin this spec was fetched from." }, { "url": "http://localhost:3000/api", "description": "Local development." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Profiles", "description": "Per-tenant containers for accounts and queue slots." }, { "name": "Accounts", "description": "Connected social accounts and account groups." }, { "name": "Connect", "description": "OAuth and direct-credential flows for connecting an account to a platform." }, { "name": "Posts", "description": "Create, schedule, publish, and retry posts across platforms." }, { "name": "Queue", "description": "Recurring auto-schedule slots." }, { "name": "Media", "description": "Pass-through media storage (no transcoding)." }, { "name": "Webhooks", "description": "Outbound event subscriptions and delivery history." }, { "name": "ApiKeys", "description": "sk_ API key lifecycle." }, { "name": "User", "description": "The currently authenticated actor." }, { "name": "Usage", "description": "Per-tenant usage counters." }, { "name": "Analytics", "description": "Per-day post/account metric rollups, daily series, and best-time-to-post suggestions." }, { "name": "Comments", "description": "Inbound comments on connected accounts' native posts, and replies to them." }, { "name": "Mentions", "description": "Inbound @-mentions across connected accounts." }, { "name": "Reviews", "description": "Platform reviews (e.g. Google Business style) and replies to them." }, { "name": "Messages", "description": "DM conversations and messages across connected accounts." }, { "name": "Contacts", "description": "CRM contact records, their channels, and bulk import." }, { "name": "CustomFields", "description": "Tenant-defined custom field schemas for Contact.customFields." }, { "name": "Broadcasts", "description": "One-shot campaign messages sent to many contacts." }, { "name": "Sequences", "description": "Multi-step drip campaigns with delay/message/broadcast steps." }, { "name": "Automations", "description": "Comment-to-DM automation rules and their trigger logs." }, { "name": "AdAccounts", "description": "Per-network connected ad accounts (Meta, Google, TikTok, LinkedIn, Pinterest, X)." }, { "name": "AdCampaigns", "description": "Ad campaigns: objective, budget, and pause/resume state." }, { "name": "Ads", "description": "Individual ads, including boosted posts, lead forms, targeting search, and conversion forwarding." }, { "name": "AdAudiences", "description": "Custom/lookalike/saved audiences and hashed-member uploads." }, { "name": "TrackingTags", "description": "Pixels, Conversions API tags, and gtag tags, plus their recorded events." } ], "paths": { "/v1/profiles": { "get": { "tags": [ "Profiles" ], "summary": "List profiles", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated list of profiles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Profiles" ], "summary": "Create a profile", "description": "Requires scope `profiles:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "Profile created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Profile" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/profiles/{id}": { "get": { "tags": [ "Profiles" ], "summary": "Get a profile", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Profile id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Profile" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Profiles" ], "summary": "Update a profile", "description": "Requires scope `profiles:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Profile id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Updated profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Profile" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Profiles" ], "summary": "Delete a profile", "description": "Requires scope `profiles:write`. Cascades to the profile's accounts and queue slots.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Profile id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List accounts", "description": "Accounts are created via the connect flow, not directly.", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "profileId", "in": "query", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/AccountStatus" } } ], "responses": { "200": { "description": "Paginated list of accounts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/accounts/{id}": { "get": { "tags": [ "Accounts" ], "summary": "Get an account", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Accounts" ], "summary": "Update an account", "description": "Requires scope `accounts:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "profileId": { "type": "string", "description": "Move the account to a different profile owned by this tenant." }, "username": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "displayName": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Updated account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Accounts" ], "summary": "Disconnect an account", "description": "Requires scope `accounts:write`. Soft-disconnect: clears stored credentials and flips status to disconnected; PostTarget history is preserved.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disconnected account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/accounts/{id}/health": { "get": { "tags": [ "Accounts" ], "summary": "Get account health", "description": "DB-derived health snapshot (does not make a live call to the platform): connection status, whether we still hold encrypted credentials, and the last recorded error.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Health snapshot.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountHealth" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account-groups": { "get": { "tags": [ "Accounts" ], "summary": "List account groups", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "profileId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of account groups.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountGroup" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Accounts" ], "summary": "Create an account group", "description": "Requires scope `account-groups:write`. Bundles accounts under a profile for bulk targeting.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profileId", "name" ], "properties": { "profileId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "accountIds": { "type": "array", "items": { "type": "string" }, "maxItems": 500 } } } } } }, "responses": { "201": { "description": "Account group created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountGroup" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account-groups/{id}": { "get": { "tags": [ "Accounts" ], "summary": "Get an account group", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account group id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The account group.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountGroup" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Accounts" ], "summary": "Update an account group", "description": "Requires scope `account-groups:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account group id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "accountIds": { "type": "array", "items": { "type": "string" }, "maxItems": 500 } } } } } }, "responses": { "200": { "description": "Updated account group.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountGroup" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Accounts" ], "summary": "Delete an account group", "description": "Requires scope `account-groups:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account group id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/connect/authorize": { "post": { "tags": [ "Connect" ], "summary": "Start connecting an account", "description": "Requires scope `accounts:connect`. For platform=mastodon this dynamically registers an OAuth app with the given instance and returns a real authUrl; for every other platform it returns mode='manual' with the fields to collect and POST to /connect/manual.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "profileId" ], "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "profileId": { "type": "string" }, "instance": { "type": "string", "description": "Mastodon instance host (e.g. \"mastodon.social\"). Required only when platform=mastodon." } } } } } }, "responses": { "200": { "description": "Connect flow details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "For platform=mastodon, mode is 'oauth' and authUrl is a real Mastodon authorization URL to redirect the user to (completes at GET /connect/callback). For every other platform, mode is 'manual' — collect `fields` from the user and POST them to /connect/manual.", "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "mode": { "type": "string", "enum": [ "oauth", "manual" ] }, "authUrl": { "type": [ "string", "null" ], "format": "uri" }, "instance": { "type": "string" }, "manualEndpoint": { "type": "string", "examples": [ "/api/v1/connect/manual" ] }, "fields": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/connect/manual": { "post": { "tags": [ "Connect" ], "summary": "Connect an account with direct credentials", "description": "Requires scope `accounts:connect`. Bypasses OAuth: validates the given credentials via the platform's PublisherAdapter.connectAccount() and persists them AES-256-GCM encrypted. Upserts on (tenantId, profileId, platform, platformAccountId).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "profileId", "credentials" ], "description": "Shape of `credentials` is discriminated by `platform`.", "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "profileId": { "type": "string" }, "credentials": { "oneOf": [ { "type": "object", "title": "BlueskyCredentials", "required": [ "identifier", "appPassword" ], "properties": { "identifier": { "type": "string", "description": "Bluesky handle or DID." }, "appPassword": { "type": "string" }, "service": { "type": "string", "format": "uri", "description": "Defaults to https://bsky.social." } } }, { "type": "object", "title": "TelegramCredentials", "required": [ "botToken", "chatId" ], "properties": { "botToken": { "type": "string" }, "chatId": { "type": "string" } } }, { "type": "object", "title": "DiscordCredentials", "required": [ "webhookUrl" ], "properties": { "webhookUrl": { "type": "string", "format": "uri" } } }, { "type": "object", "title": "MastodonCredentials", "required": [ "instance", "accessToken" ], "properties": { "instance": { "type": "string" }, "accessToken": { "type": "string" } } } ] } } } } } }, "responses": { "200": { "description": "Existing account reconnected.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "201": { "description": "New account connected.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/connect/callback": { "get": { "tags": [ "Connect" ], "summary": "Mastodon OAuth callback", "description": "Redirect target for the Mastodon OAuth flow started by POST /connect/authorize. Not called with a Bearer sk_ key — tenant/profile authorization is instead proven by successfully decrypting the `state` query param, which was minted server-side after the original caller passed authenticate()+requireScope('accounts:connect').", "security": [], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "error", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Existing account reconnected.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "201": { "description": "New account connected.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/posts": { "get": { "tags": [ "Posts" ], "summary": "List posts", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/PostStatus" } }, { "name": "source", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of posts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Posts" ], "summary": "Create (and optionally schedule/publish) a post", "description": "Requires scope `posts:write`. One PostTarget is created per accountId. If `publishNow` is true the post is claimed by the next cron tick immediately; if `scheduledFor` is set it publishes at that time; otherwise it is saved as a draft. Publishing always goes through the scheduler (claimDuePosts/publishPost) — never directly through adapters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content", "accountIds" ], "properties": { "content": { "type": "string", "minLength": 1 }, "accountIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Accounts (owned by this tenant) to publish this post to — one PostTarget is created per account." }, "mediaAssetIds": { "type": "array", "items": { "type": "string" }, "description": "Previously uploaded MediaAsset ids." }, "scheduledFor": { "type": "string", "format": "date-time", "description": "Omit together with publishNow=false to save as a draft." }, "publishNow": { "type": "boolean", "default": false }, "source": { "type": "string", "default": "api" } } } } } }, "responses": { "201": { "description": "Post created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Post" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/posts/{id}": { "get": { "tags": [ "Posts" ], "summary": "Get a post", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Post id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The post, including its targets and media.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Post" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Posts" ], "summary": "Update a post", "description": "Requires scope `posts:write`. Only posts in status draft or scheduled may be updated.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Post id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "description": "Only posts in status draft or scheduled may be updated.", "properties": { "content": { "type": "string", "minLength": 1 }, "accountIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "mediaAssetIds": { "type": "array", "items": { "type": "string" } }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "responses": { "200": { "description": "Updated post.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Post" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "tags": [ "Posts" ], "summary": "Delete a post", "description": "Requires scope `posts:write`. Cascades to its PostTarget and PostMedia rows.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Post id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/posts/{id}/retry": { "post": { "tags": [ "Posts" ], "summary": "Retry a post's failed targets", "description": "Requires scope `posts:write`. Calls retryPost() from the scheduler — only re-attempts PostTarget rows currently in status failed; published targets are never re-sent.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Post id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post after retry, with updated target statuses.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Post" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/posts/validate": { "post": { "tags": [ "Posts" ], "summary": "Pre-flight validate content against target platforms", "description": "Any authenticated API key (no extra scope). Read-only: reports whether `content` fits each target platform's character limit and whether the referenced `accountId`s are valid/connected, without creating anything.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content", "platforms" ], "properties": { "content": { "type": "string", "minLength": 1 }, "platforms": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "platform" ], "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "accountId": { "type": "string", "description": "When given, also checked for tenant ownership, platform match, and isConnected." } } } } } } } } }, "responses": { "200": { "description": "Per-platform validation results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "True iff every entry in `results` is ok." }, "results": { "type": "array", "items": { "type": "object", "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "accountId": { "type": [ "string", "null" ] }, "length": { "type": "integer" }, "limit": { "type": "integer", "description": "Platform character limit." }, "ok": { "type": "boolean" }, "error": { "type": "string" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/queue": { "get": { "tags": [ "Queue" ], "summary": "List queue slots", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "profileId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of recurring queue slots.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueueSlot" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Queue" ], "summary": "Create a queue slot", "description": "Requires scope `queue:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profileId", "dayOfWeek", "timeOfDay" ], "properties": { "profileId": { "type": "string" }, "dayOfWeek": { "type": "integer", "minimum": 0, "maximum": 6 }, "timeOfDay": { "type": "integer", "minimum": 0, "maximum": 1439 }, "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Queue slot created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/QueueSlot" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/queue/preview": { "get": { "tags": [ "Queue" ], "summary": "Preview upcoming queue slot occurrences", "description": "Any authenticated API key (no extra scope). Read-only projection of a profile's enabled QueueSlots into their next N upcoming UTC occurrences; does not read or write any Post.", "parameters": [ { "name": "profileId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Defaults to 10, capped at 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "from", "in": "query", "description": "ISO 8601 instant to project from. Defaults to now.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Upcoming occurrences, soonest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "queueSlotId": { "type": "string" }, "dayOfWeek": { "type": "integer", "minimum": 0, "maximum": 6 }, "timeOfDay": { "type": "integer", "minimum": 0, "maximum": 1439 }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/queue/{id}": { "get": { "tags": [ "Queue" ], "summary": "Get a queue slot", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Queue slot id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The queue slot.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/QueueSlot" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Queue" ], "summary": "Update a queue slot", "description": "Requires scope `queue:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Queue slot id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "dayOfWeek": { "type": "integer", "minimum": 0, "maximum": 6 }, "timeOfDay": { "type": "integer", "minimum": 0, "maximum": 1439 }, "timezone": { "type": "string" }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated queue slot.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/QueueSlot" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Queue" ], "summary": "Delete a queue slot", "description": "Requires scope `queue:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Queue slot id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/media/upload": { "post": { "tags": [ "Media" ], "summary": "Upload media", "description": "Requires scope `media:write`. Accepts multipart/form-data (field `file`) or a JSON body with `url` (fetched pass-through and re-hosted) or `dataBase64`. Bytes are stored as-is — no transcoding. 25MB max.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "altText": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } }, "application/json": { "schema": { "type": "object", "description": "Alternative to multipart/form-data: provide either `url` (fetched pass-through and re-hosted) or `dataBase64`.", "properties": { "url": { "type": "string", "format": "uri" }, "dataBase64": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "altText": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } } }, "responses": { "201": { "description": "MediaAsset created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MediaAsset" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/media/presign": { "post": { "tags": [ "Media" ], "summary": "Pre-negotiate an upload slot", "description": "Requires scope `media:write`. Returns a short-lived, tenant-bound token plus the URL/method/field name to POST bytes to (currently /v1/media/upload — swappable for a real object-storage presigned URL later without changing callers).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "mimeType": { "type": "string" } } } } } }, "responses": { "201": { "description": "Presign details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "uploadUrl": { "type": "string", "format": "uri" }, "method": { "type": "string", "examples": [ "POST" ] }, "fieldName": { "type": "string", "examples": [ "file" ] }, "token": { "type": "string", "description": "Opaque, AES-256-GCM-encrypted upload token bound to this tenant/key." }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/validate/media-url": { "post": { "tags": [ "Media" ], "summary": "Validate a remote media URL", "description": "Read-only pre-flight check (any valid API key, no extra scope): confirms the URL is reachable, resolves its mime type/size, without downloading or storing it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Validation result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "mimeType": { "type": [ "string", "null" ] }, "sizeBytes": { "type": [ "integer", "null" ] }, "type": { "$ref": "#/components/schemas/MediaType" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated list of webhooks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Requires scope `webhooks:write`. The response is the ONLY place `secret` (used to compute X-OneSocial-Signature) is ever returned.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "minItems": 1 }, "enabled": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Webhook created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookCreated" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The webhook.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Requires scope `webhooks:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "minItems": 1 }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated webhook.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Requires scope `webhooks:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/webhooks/{id}/logs": { "get": { "tags": [ "Webhooks" ], "summary": "List a webhook's delivery history", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated WebhookDelivery rows for this webhook, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/webhooks/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test delivery", "description": "Requires scope `webhooks:write`. Sends a one-off `webhook.test` delivery to the given webhook regardless of its subscribed events list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhookId" ], "properties": { "webhookId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Delivery attempt result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/api-keys": { "get": { "tags": [ "ApiKeys" ], "summary": "List API keys", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated list of API keys (never includes keyHash).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "ApiKeys" ], "summary": "Create an API key", "description": "Requires scope `api-keys:write`. The raw sk_ value is returned ONCE in this response and is never retrievable again.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "default": [], "description": "Empty array grants full access." } } } } } }, "responses": { "201": { "description": "API key created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeyCreated" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/api-keys/{id}": { "delete": { "tags": [ "ApiKeys" ], "summary": "Revoke an API key", "description": "Requires scope `api-keys:write`. Sets revokedAt; the key immediately stops authenticating.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/user": { "get": { "tags": [ "User" ], "summary": "Get the current actor", "description": "Returns the tenant and API key identity behind the bearer sk_ token used on this request.", "responses": { "200": { "description": "Current actor identity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "tenantId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "tenant": { "$ref": "#/components/schemas/Tenant" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Get usage summary", "description": "Account and post counters for the authenticated tenant. `from`/`to` default to the current UTC calendar month.", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Usage summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "accounts": { "type": "object", "properties": { "total": { "type": "integer" }, "connected": { "type": "integer" }, "byPlatform": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "posts": { "type": "object", "properties": { "total": { "type": "integer" }, "scheduled": { "type": "integer" }, "published": { "type": "integer" }, "partial": { "type": "integer" }, "failed": { "type": "integer" }, "createdThisPeriod": { "type": "integer" }, "publishedThisPeriod": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Get an analytics rollup", "description": "Requires scope `analytics:read`. Sums the typed PostMetric counters across `since`/`until` (default: trailing 30 days).", "parameters": [ { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "accountId", "in": "query", "schema": { "type": "string" } }, { "name": "postId", "in": "query", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } } ], "responses": { "200": { "description": "Analytics summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The flat counters (impressions/reach/.../saves) are duplicated at the top level (mirroring GET /v1/usage's flat+nested convention) and inside `totals`.", "properties": { "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "clicks": { "type": "integer" }, "saves": { "type": "integer" }, "period": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" } } }, "totals": { "type": "object", "properties": { "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "clicks": { "type": "integer" }, "saves": { "type": "integer" } } }, "byPlatform": { "type": "array", "items": { "type": "object", "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "clicks": { "type": "integer" }, "saves": { "type": "integer" } } } }, "snapshotCount": { "type": "integer", "minimum": 0, "description": "Number of PostMetric rows contributing to this summary." }, "filters": { "type": "object", "properties": { "accountId": { "type": [ "string", "null" ] }, "postId": { "type": [ "string", "null" ] }, "platform": { "anyOf": [ { "$ref": "#/components/schemas/Platform" }, { "type": "null" } ] } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/analytics/daily": { "get": { "tags": [ "Analytics" ], "summary": "Get analytics grouped by day", "description": "Requires scope `analytics:read`. Same filters as GET /analytics, grouped by PostMetric.date for charting.", "parameters": [ { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "accountId", "in": "query", "schema": { "type": "string" } }, { "name": "postId", "in": "query", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } } ], "responses": { "200": { "description": "Daily analytics points, ascending by date.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "clicks": { "type": "integer" }, "saves": { "type": "integer" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/analytics/best-time": { "get": { "tags": [ "Analytics" ], "summary": "Get the best time to post", "description": "Requires scope `analytics:read`. Buckets PostMetric rows by weekday x hour and ranks by engagement, to suggest optimal posting slots.", "parameters": [ { "name": "accountId", "in": "query", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Ranked weekday x hour slots, best first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0=Sunday .. 6=Saturday" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "score": { "type": "number", "description": "Aggregate engagement score for this weekday x hour bucket." }, "sampleSize": { "type": "integer", "minimum": 0, "description": "Number of PostMetric rows contributing to this bucket." } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/comments": { "get": { "tags": [ "Comments" ], "summary": "List comments", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "accountId", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/CommentStatus" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "postId", "in": "query", "schema": { "type": "string" } }, { "name": "parentId", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive substring match against comment text.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of comments, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/comments/{id}": { "get": { "tags": [ "Comments" ], "summary": "Get a comment", "description": "Includes its threaded replies (Comment rows with parentId set) as `replies`, oldest first.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Comment id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The comment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Comment" }, { "type": "object", "properties": { "replies": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Comments" ], "summary": "Delete/hide a comment", "description": "Requires scope `comments:write`. Marks the comment status = deleted; does not remove the row.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Comment id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted comment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Comment" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/comments/{id}/reply": { "post": { "tags": [ "Comments" ], "summary": "Reply to a comment", "description": "Requires scope `comments:write`. Persists the reply as a new Comment row (isOwn=true, parentId set to the original), flips the original's status to replied, and dispatches `comment.replied`. 409 if the original comment is already status=deleted.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Comment id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1 } } } } } }, "responses": { "201": { "description": "The original comment (now status=replied) and the new reply comment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" }, "reply": { "$ref": "#/components/schemas/Comment" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/mentions": { "get": { "tags": [ "Mentions" ], "summary": "List mentions", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint). Read-only — mentions have no reply concept.", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "accountId", "in": "query", "schema": { "type": "string" } }, { "name": "isRead", "in": "query", "schema": { "type": "boolean" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "q", "in": "query", "description": "Case-insensitive substring match against mention text.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of mentions, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/reviews": { "get": { "tags": [ "Reviews" ], "summary": "List reviews", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "accountId", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ReviewStatus" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "rating", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "q", "in": "query", "description": "Case-insensitive substring match against review text.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of reviews, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/reviews/{id}": { "get": { "tags": [ "Reviews" ], "summary": "Get a review", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Review id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The review.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Review" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/reviews/{id}/reply": { "post": { "tags": [ "Reviews" ], "summary": "Reply to a review", "description": "Requires scope `reviews:write`. Sets reply/repliedAt and status=replied, and dispatches `review.replied`. Re-posting to an already-replied review overwrites the stored reply (edit-in-place; there is a single `reply` field, not a thread).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Review id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "The updated review.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Review" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/messages": { "get": { "tags": [ "Messages" ], "summary": "List conversations", "description": "Requires scope `messages:read`. Despite the path, this lists Conversation rows (message threads), sorted by lastMessageAt.", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "accountId", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ConversationStatus" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "contactId", "in": "query", "schema": { "type": "string" } }, { "name": "unread", "in": "query", "description": "true = unreadCount > 0, false = unreadCount == 0.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated list of conversations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/conversations/{id}": { "get": { "tags": [ "Messages" ], "summary": "Get a conversation", "description": "Requires scope `messages:read`. Includes its messages, oldest first.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The conversation with messages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/conversations/{id}/mark-read": { "post": { "tags": [ "Messages" ], "summary": "Mark a conversation read", "description": "Requires scope `messages:write`. Sets unreadCount=0 and isRead=true on its inbound messages.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The updated conversation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/messages/send": { "post": { "tags": [ "Messages" ], "summary": "Send a DM", "description": "Requires scope `messages:write`. Sends via the platform adapter and records an outbound Message; pass `conversationId` to append to an existing thread, or `accountId`+`contactId` to start a new one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "description": "Provide either `conversationId` to append to an existing thread, or `contactId` + `accountId` to start/continue one with that contact on that account.", "properties": { "conversationId": { "type": "string", "description": "Existing Conversation to append to." }, "contactId": { "type": "string", "description": "Required (with accountId) when conversationId is omitted." }, "accountId": { "type": "string", "description": "Required (with contactId) when conversationId is omitted." }, "platform": { "$ref": "#/components/schemas/Platform", "description": "Optional assertion that must match the account's platform." }, "text": { "type": "string", "minLength": 1 }, "attachments": { "type": [ "object", "array", "null" ] } } } } } }, "responses": { "201": { "description": "The sent message.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Message" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/messages/{id}": { "patch": { "tags": [ "Messages" ], "summary": "Edit a message", "description": "Requires scope `messages:write`. Only own outbound messages may be edited; sets editedAt.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Message id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "The updated message.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Message" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Messages" ], "summary": "Delete a message", "description": "Requires scope `messages:write`. Soft-delete: sets deletedAt and status=deleted; thread ordering is preserved.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Message id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted message.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Message" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "Requires scope `contacts:read`.", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "q", "in": "query", "description": "Case-insensitive substring match against first/last name or email.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string", "format": "email" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of contacts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "description": "Requires scope `contacts:write`. `customFields` is validated against this tenant's CustomFieldDef rows via validateCustomFields() before persistence.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 200 }, "lastName": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 50 }, "avatarUrl": { "type": "string", "format": "uri", "maxLength": 2000 }, "notes": { "type": "string", "maxLength": 5000 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 200 }, "customFields": { "type": "object", "description": "Validated against this tenant's CustomFieldDef rows before persistence. Use POST /contacts/{id}/channels to attach delivery channels after creation." } } } } } }, "responses": { "201": { "description": "Contact created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/contacts/bulk-create": { "post": { "tags": [ "Contacts" ], "summary": "Bulk-create contacts", "description": "Requires scope `contacts:write`. Up to 1000 contacts per call; each is validated (including customFields) before a single createMany.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 200 }, "lastName": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 50 }, "avatarUrl": { "type": "string", "format": "uri", "maxLength": 2000 }, "notes": { "type": "string", "maxLength": 5000 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 200 }, "customFields": { "type": "object", "description": "Validated against this tenant's CustomFieldDef rows before persistence. Use POST /contacts/{id}/channels to attach delivery channels after creation." } } }, "minItems": 1, "maxItems": 1000 } } } } } }, "responses": { "201": { "description": "Bulk-create result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "count": { "type": "integer" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Get a contact", "description": "Requires scope `contacts:read`. Includes channels.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The contact.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Requires scope `contacts:write`. `customFields`, if present, is re-validated in full against this tenant's CustomFieldDef rows.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri" }, "notes": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "description": "Validated against this tenant's CustomFieldDef rows before persistence." } } } } } }, "responses": { "200": { "description": "Updated contact.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "description": "Requires scope `contacts:write`. Cascades to its channels, broadcast recipient rows, and sequence enrollments.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/contacts/{id}/channels": { "post": { "tags": [ "Contacts" ], "summary": "Add a channel to a contact", "description": "Requires scope `contacts:write`. Rejects with 409 if this exact (platform, externalId) is already attached to the contact — unique per (contactId, platform, externalId).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "externalId" ], "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "externalId": { "type": "string", "minLength": 1, "maxLength": 500 }, "accountId": { "type": "string", "description": "When given, must be a tenant account on the same platform." }, "handle": { "type": [ "string", "null" ], "maxLength": 200 } } } } } }, "responses": { "201": { "description": "Channel added.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ContactChannel" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/custom-fields": { "get": { "tags": [ "CustomFields" ], "summary": "List custom field definitions", "description": "Requires scope `custom-fields:read`.", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated list of custom field defs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDef" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "CustomFields" ], "summary": "Create a custom field definition", "description": "Requires scope `custom-fields:write`. Unique per tenant on `key`; 409 if that key already exists.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "$ref": "#/components/schemas/CustomFieldType" }, "required": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "string" }, "description": "Allowed values when type = select." } } } } } }, "responses": { "201": { "description": "Custom field def created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDef" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/custom-fields/{id}": { "get": { "tags": [ "CustomFields" ], "summary": "Get a custom field definition", "description": "Requires scope `custom-fields:read`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Custom field def id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The custom field def.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDef" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "CustomFields" ], "summary": "Update a custom field definition", "description": "Requires scope `custom-fields:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Custom field def id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "description": "`key` is immutable after creation (it's used verbatim inside stored Contact.customFields JSON); every other field, including `type`, may be changed.", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "$ref": "#/components/schemas/CustomFieldType" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" }, "description": "Must be a non-empty array when the resulting type is 'select'." } } } } } }, "responses": { "200": { "description": "Updated custom field def.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDef" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "CustomFields" ], "summary": "Delete a custom field definition", "description": "Requires scope `custom-fields:write`. Does not retroactively strip the key from existing Contact.customFields JSON.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Custom field def id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/broadcasts": { "get": { "tags": [ "Broadcasts" ], "summary": "List broadcasts", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/BroadcastStatus" } } ], "responses": { "200": { "description": "Paginated list of broadcasts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Broadcasts" ], "summary": "Create a broadcast", "description": "Requires scope `broadcasts:write`. Created in status=draft (or scheduled, when `scheduledFor` is given); optionally seeds BroadcastRecipient rows from `contactIds`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "message" ], "description": "`platform` is required only when `accountId` is omitted (it's otherwise inferred from the account).", "properties": { "accountId": { "type": "string" }, "platform": { "$ref": "#/components/schemas/Platform" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "message": { "type": "string", "minLength": 1 }, "contactIds": { "type": "array", "items": { "type": "string" }, "description": "Optional initial recipient set. Contacts with no matching ContactChannel for the resolved platform are skipped (see `skippedContactIds` in the response) rather than failing the request." }, "scheduledFor": { "type": "string", "format": "date-time", "description": "When set, the broadcast is created in status=scheduled instead of draft." } } } } } }, "responses": { "201": { "description": "Broadcast created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Broadcast" }, { "type": "object", "properties": { "skippedContactIds": { "type": "array", "items": { "type": "string" }, "description": "contactIds that had no matching ContactChannel for the resolved platform, so were not seeded as recipients." } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/broadcasts/{id}": { "get": { "tags": [ "Broadcasts" ], "summary": "Get a broadcast", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint). Includes its recipients.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Broadcast id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The broadcast.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Broadcast" }, { "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastRecipient" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Broadcasts" ], "summary": "Update a broadcast", "description": "Requires scope `broadcasts:write`. Only broadcasts in status draft or scheduled may be updated. Passing `contactIds` deletes all existing BroadcastRecipient rows for this broadcast and re-creates them (there is no separate add-recipients endpoint).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Broadcast id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "description": "Only broadcasts in status draft or scheduled may be updated. Passing `contactIds` fully replaces the existing recipient set (there is no separate add-recipients endpoint).", "properties": { "accountId": { "type": [ "string", "null" ] }, "platform": { "$ref": "#/components/schemas/Platform" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "message": { "type": "string", "minLength": 1 }, "contactIds": { "type": "array", "items": { "type": "string" }, "description": "Replaces all existing BroadcastRecipient rows for this broadcast." }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time", "description": "A non-null value moves status to scheduled; null moves it back to draft." } } } } } }, "responses": { "200": { "description": "Updated broadcast.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Broadcast" }, { "type": "object", "properties": { "skippedContactIds": { "type": "array", "items": { "type": "string" }, "description": "Present when `contactIds` was provided: entries with no matching ContactChannel for the resolved platform." } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "tags": [ "Broadcasts" ], "summary": "Cancel a broadcast", "description": "Requires scope `broadcasts:write`. Despite the HTTP method this does NOT delete the row: only broadcasts in status draft or scheduled may be cancelled; it marks their pending BroadcastRecipient rows status=skipped and sets the broadcast status=cancelled. There is no separate /cancel endpoint.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Broadcast id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The cancelled broadcast.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/broadcasts/{id}/send": { "post": { "tags": [ "Broadcasts" ], "summary": "Send a broadcast now", "description": "Requires scope `broadcasts:write`. Sets status=sending for the /api/cron/engage broadcasts pass to pick up immediately.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Broadcast id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The broadcast, now sending.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/broadcasts/{id}/schedule": { "post": { "tags": [ "Broadcasts" ], "summary": "Schedule a broadcast", "description": "Requires scope `broadcasts:write`. Sets status=scheduled and scheduledFor for the cron pass to claim once due.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Broadcast id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduledFor" ], "properties": { "scheduledFor": { "type": "string", "format": "date-time", "description": "Must be in the future." } } } } } }, "responses": { "200": { "description": "The scheduled broadcast.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/sequences": { "get": { "tags": [ "Sequences" ], "summary": "List sequences", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/SequenceStatus" } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "accountId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of sequences.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sequence" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Sequences" ], "summary": "Create a sequence", "description": "Requires scope `sequences:write`. Created in status=draft (unless `status` is given) with the given inline `steps` (defaults to an empty array).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "accountId": { "type": "string" }, "platform": { "$ref": "#/components/schemas/Platform" }, "status": { "$ref": "#/components/schemas/SequenceStatus", "description": "Defaults to draft." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "steps": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "delay", "message", "broadcast" ] }, "content": { "type": "string" }, "delayHours": { "type": "number" } } }, "maxItems": 50, "description": "Defaults to an empty array. `delay` steps require delayHours; `message`/`broadcast` steps require content." } } } } } }, "responses": { "201": { "description": "Sequence created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sequences/{id}": { "get": { "tags": [ "Sequences" ], "summary": "Get a sequence", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sequence id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The sequence.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Sequences" ], "summary": "Update a sequence", "description": "Requires scope `sequences:write`. Sets `status` to active/paused/draft here — there are no separate activate/pause endpoints.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sequence id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "description": "Only draft/active/paused transitions are supported for `status` (set it to `active` or `paused` here; there are no separate activate/pause endpoints).", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "accountId": { "type": [ "string", "null" ] }, "platform": { "anyOf": [ { "$ref": "#/components/schemas/Platform" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/SequenceStatus" }, "steps": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "delay", "message", "broadcast" ] }, "content": { "type": "string" }, "delayHours": { "type": "number" } } }, "maxItems": 50 } } } } } }, "responses": { "200": { "description": "Updated sequence.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "tags": [ "Sequences" ], "summary": "Delete a sequence", "description": "Requires scope `sequences:write`. Hard-deletes the row (there is no cancelled status for sequences); rejected with 409 while any enrollment is still status=active.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sequence id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/sequences/{id}/enroll": { "post": { "tags": [ "Sequences" ], "summary": "Enroll a contact in a sequence", "description": "Requires scope `sequences:write`. Upserts a single SequenceEnrollment row on (sequenceId, contactId) with status=active, currentStep=0, and nextRunAt derived from the first step. There is no separate unenroll endpoint or bulk form — call this once per contactId, and set the enrollment's status via a client-side record if you need to track unenrollment (the API itself has no route for it yet).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sequence id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contactId" ], "description": "Enrolls one contact per call. Re-enrolling a contact whose enrollment is status=completed or unenrolled restarts it at step 0; any other existing status is a 409 conflict.", "properties": { "contactId": { "type": "string" } } } } } }, "responses": { "200": { "description": "An existing completed/unenrolled enrollment was reset and restarted at step 0.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SequenceEnrollment" } } } } } }, "201": { "description": "New enrollment created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SequenceEnrollment" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The contact already has an active or paused enrollment in this sequence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/automations/comment-to-dm": { "get": { "tags": [ "Automations" ], "summary": "List comment-to-DM automations", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "accountId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of automations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommentAutomation" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Automations" ], "summary": "Create a comment-to-DM automation", "description": "Requires scope `automations:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accountId", "keywords", "dmMessage" ], "description": "`platform` is always derived from `accountId` and is not accepted here. `name` defaults to \"Comment automation for \" when omitted.", "properties": { "accountId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "enabled": { "type": "boolean", "default": true }, "keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "matchType": { "type": "string", "enum": [ "any", "all", "exact" ], "default": "any" }, "dmMessage": { "type": "string", "minLength": 1 }, "replyMessage": { "type": "string" } } } } } }, "responses": { "201": { "description": "Automation created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommentAutomation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/comment-to-dm/{id}": { "get": { "tags": [ "Automations" ], "summary": "Get a comment-to-DM automation", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Automation id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The automation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommentAutomation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Automations" ], "summary": "Update a comment-to-DM automation", "description": "Requires scope `automations:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Automation id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "description": "`accountId`, when given, re-derives `platform` from the new account.", "properties": { "accountId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "enabled": { "type": "boolean" }, "keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "matchType": { "type": "string", "enum": [ "any", "all", "exact" ] }, "dmMessage": { "type": "string", "minLength": 1 }, "replyMessage": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Updated automation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommentAutomation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Automations" ], "summary": "Delete a comment-to-DM automation", "description": "Requires scope `automations:write`. Cascades to its trigger logs.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Automation id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/comment-to-dm/{id}/logs": { "get": { "tags": [ "Automations" ], "summary": "List an automation's trigger logs", "description": "Any authenticated API key (read-scope enforcement not yet applied to this endpoint).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Automation id.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "1-indexed page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated CommentAutomationLog rows, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "limit", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommentAutomationLog" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/media/file/{tenantId}/{filename}": { "get": { "tags": [ "Media" ], "summary": "Serve an uploaded media file from disk", "description": "Not bearer-authenticated on purpose — URLs returned by POST /v1/media/upload are embedded directly in outbound posts/DMs and rendered in /