# This file is rendered from src/openapi/spec.ts (the single source of truth) # via src/openapi/to-yaml.ts. Do not hand-edit — regenerate with: # node scripts/generate-openapi-yaml.mjs # after changing src/openapi/spec.ts. The JSON served by GET /api/openapi and # the YAML served by GET /api/openapi?format=yaml come from the same # in-memory object at request time, so they can never drift from this file. 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 /