Antwork Accounts API

openapi: 3.2.0
info:
  title: Antwork Accounts API
  version: v1
  description: 'Draft, schedule and publish social posts on the accounts connected to your Antwork workspaces. Reference: https://antwork.io/docs/api'
servers:
- url: https://antwork.io/api/v1
security:
- apiKey: []
tags:
- name: Accounts
paths:
  /accounts:
    get:
      operationId: listAccounts
      summary: Connected accounts, their ids and their token health
      description: 'Scope: `read`.


        Docs: https://antwork.io/docs/api/list-accounts'
      x-antwork-scope: read
      externalDocs:
        url: https://antwork.io/docs/api/list-accounts
      parameters:
      - name: workspaceId
        in: query
        required: false
        description: Only accounts in this workspace.
        schema:
          type: string
      - name: platform
        in: query
        required: false
        description: Only accounts on this platform.
        schema:
          type: string
      responses:
        '200':
          description: Every connected account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountList'
        '401':
          description: 'No usable API key. Codes: `api_key_missing`, `api_key_malformed`, `api_key_unknown`, `api_key_revoked`.'
          x-error-codes:
          - api_key_missing
          - api_key_malformed
          - api_key_unknown
          - api_key_revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The key cannot do this. Codes: `insufficient_scope`, `subscription_inactive`.'
          x-error-codes:
          - insufficient_scope
          - subscription_inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited. See the X-RateLimit-* and Retry-After headers. Codes: `rate_limit_burst`, `rate_limit_daily`.'
          x-error-codes:
          - rate_limit_burst
          - rate_limit_daily
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'Something went wrong on our end. Codes: `internal_error`.'
          x-error-codes:
          - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Accounts
  /accounts/{accountId}:
    get:
      operationId: getAccount
      summary: One account, the settings a post to it takes, its Pinterest boards and its…
      description: 'Scope: `read`.


        Docs: https://antwork.io/docs/api/get-account'
      x-antwork-scope: read
      externalDocs:
        url: https://antwork.io/docs/api/get-account
      parameters:
      - name: accountId
        in: path
        required: true
        description: An account id from GET /accounts.
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: 'Comma-separated: `recentPosts` (the account’s posts, its voice; may read the platform, so it counts toward the platform-read limit) and `bestTimes`.'
        schema:
          type: string
      responses:
        '200':
          description: The account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDetail'
        '400':
          description: 'The request was refused. Codes: `invalid_filter`.'
          x-error-codes:
          - invalid_filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'No usable API key. Codes: `api_key_missing`, `api_key_malformed`, `api_key_unknown`, `api_key_revoked`.'
          x-error-codes:
          - api_key_missing
          - api_key_malformed
          - api_key_unknown
          - api_key_revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The key cannot do this. Codes: `insufficient_scope`, `subscription_inactive`.'
          x-error-codes:
          - insufficient_scope
          - subscription_inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Not found on this account. Codes: `account_not_found`.'
          x-error-codes:
          - account_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited. See the X-RateLimit-* and Retry-After headers. Codes: `platform_read_rate_limited`, `rate_limit_burst`, `rate_limit_daily`.'
          x-error-codes:
          - platform_read_rate_limited
          - rate_limit_burst
          - rate_limit_daily
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'Something went wrong on our end. Codes: `internal_error`.'
          x-error-codes:
          - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Accounts
    patch:
      operationId: updateAccount
      summary: 'Set the account’s own posting rules: a daily maximum, a minimum gap between…'
      description: 'Enforced like the platform caps: a post that breaks one is refused with `account_limit_reached` and `nextFreeAt`. `slots` are what `scheduledFor: "next_slot"` fills. The same settings as the web’s posting schedule and MCP `update_workspace(account_posting=…)`.


        Scope: `write`.


        Docs: https://antwork.io/docs/api/get-account'
      x-antwork-scope: write
      externalDocs:
        url: https://antwork.io/docs/api/get-account
      parameters:
      - name: accountId
        in: path
        required: true
        description: An account id from GET /accounts.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdate'
      responses:
        '200':
          description: The account with its settings as saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDetail'
        '400':
          description: 'The request was refused. Codes: `invalid_body`, `invalid_posting_settings`.'
          x-error-codes:
          - invalid_body
          - invalid_posting_settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'No usable API key. Codes: `api_key_missing`, `api_key_malformed`, `api_key_unknown`, `api_key_revoked`.'
          x-error-codes:
          - api_key_missing
          - api_key_malformed
          - api_key_unknown
          - api_key_revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The key cannot do this. Codes: `role_forbidden`, `insufficient_scope`, `subscription_inactive`.'
          x-error-codes:
          - role_forbidden
          - insufficient_scope
          - subscription_inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Not found on this account. Codes: `account_not_found`.'
          x-error-codes:
          - account_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited. See the X-RateLimit-* and Retry-After headers. Codes: `rate_limit_burst`, `rate_limit_daily`.'
          x-error-codes:
          - rate_limit_burst
          - rate_limit_daily
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'Something went wrong on our end. Codes: `internal_error`.'
          x-error-codes:
          - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Accounts
  /accounts/{accountId}/platform-posts:fetch:
    post:
      operationId: fetchPlatformPosts
      summary: The account’s recent posts read back from the platform itself, with metrics and…
      description: 'MCP fetch_platform_posts for one account. A POST because it spends the account’s platform API quota; at most 10 per key per 10 minutes. A LinkedIn personal profile cannot be read back and answers `unsupported: true`.


        Scope: `read`.


        Docs: https://antwork.io/docs/api/platform-posts'
      x-antwork-scope: read
      externalDocs:
        url: https://antwork.io/docs/api/platform-posts
      parameters:
      - name: accountId
        in: path
        required: true
        description: An account id from GET /accounts.
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformPostsFetch'
      responses:
        '200':
          description: The posts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformPosts'
        '400':
          description: 'The request was refused. Codes: `invalid_body`, `invalid_limit`.'
          x-error-codes:
          - invalid_body
          - invalid_limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'No usable API key. Codes: `api_key_missing`, `api_key_malformed`, `api_key_unknown`, `api_key_revoked`.'
          x-error-codes:
          - api_key_missing
          - api_key_malformed
          - api_key_unknown
          - api_key_revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The key cannot do this. Codes: `insufficient_scope`, `subscription_inactive`.'
          x-error-codes:
          - insufficient_scope
          - subscription_inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Not found on this account. Codes: `account_not_found`.'
          x-error-codes:
          - account_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'Conflict. Codes: `account_inactive`, `token_invalid`.'
          x-error-codes:
          - account_inactive
          - token_invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited. See the X-RateLimit-* and Retry-After headers. Codes: `platform_read_rate_limited`, `rate_limit_burst`, `rate_limit_daily`.'
          x-error-codes:
          - platform_read_rate_limited
          - rate_limit_burst
          - rate_limit_daily
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'Something went wrong on our end. Codes: `internal_error`.'
          x-error-codes:
          - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Accounts
components:
  schemas:
    TikTokChoices:
      type: object
      description: 'With `tiktok_choices_needed`: what to put in front of the user before a TikTok post goes. Build the UI from it; never pick for the user.'
      properties:
        creator:
          type: object
          properties:
            nickname:
              type:
              - string
              - 'null'
            avatarUrl:
              type:
              - string
              - 'null'
        privacyLevel:
          type: object
          description: 'No default: `default` is always null.'
          properties:
            default:
              type: 'null'
            options:
              type: array
              items:
                type: object
                properties:
                  value:
                    type: string
                  label:
                    type: string
            notWithBrandedContent:
              type: array
              items:
                type: string
        interactions:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              label:
                type: string
              default:
                const: false
              disabledByCreator:
                type: boolean
        commercialContent:
          type: object
          description: Off by default; once on, at least one of `yourBrand` / `brandedContent`, each with the label TikTok shows.
        aiGenerated:
          type: object
        maxVideoPostDurationSec:
          type:
          - integer
          - 'null'
        videoDurationSec:
          type: number
        declaration:
          type: object
          description: 'Shown, with its links, and agreed to before `userConsented: true` is sent.'
          properties:
            text:
              type: string
            textWithBrandedContent:
              type: string
            links:
              type: object
              additionalProperties:
                type: string
            requiresConsent:
              const: true
        preview:
          type: object
          properties:
            text:
              type: string
            mediaUrls:
              type: array
              items:
                type: string
        lastUsed:
          type: object
          description: 'The account''s last answers that still apply, when it has some: ask the user once, then send `{useLast: true, userConsented: true}`.'
          properties:
            settings:
              type: object
            summary:
              type: string
        nextStep:
          type: string
    SettingField:
      type: object
      required:
      - key
      - label
      - type
      properties:
        key:
          type: string
        label:
          type: string
        type:
          type: string
          enum:
          - enum
          - bool
          - text
          - url
        options:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              label:
                type: string
        default: {}
        maxLength:
          type: integer
        placeholder:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          properties:
            type:
              type: string
              enum:
              - authentication_error
              - permission_error
              - invalid_request_error
              - rate_limit_error
              - api_error
            code:
              type: string
              description: Stable identifier to branch on. See /docs/api/errors.
            message:
              type: string
              description: For a human reading a log; may change.
            param:
              type: string
              description: The offending field, when one can be named.
            tiktokChoices:
              $ref: '#/components/schemas/TikTokChoices'
            problems:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
              description: '`tiktok_choices_needed` after settings were sent: what was wrong with each.'
            settingsUrl:
              type: string
              description: '`tiktok_choices_needed`: the post in the composer with its settings open.'
    PlatformPosts:
      type: object
      required:
      - object
      - accountId
      - platform
      - posts
      - postCount
      properties:
        object:
          const: platform_posts
        accountId:
          type: string
        workspaceId:
          type: string
        platform:
          type: string
        accountName:
          type: string
        accountHandle:
          type: string
        unsupported:
          const: true
          description: This account cannot be read back (a LinkedIn personal profile).
        unsupportedReason:
          type: string
        posts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              text:
                type: string
              publishedAt:
                type:
                - string
                - 'null'
              engagementMetrics:
                type:
                - object
                - 'null'
              mediaType:
                type:
                - string
                - 'null'
              permalink:
                type:
                - string
                - 'null'
        postCount:
          type: integer
    AccountList:
      type: object
      required:
      - object
      - accounts
      properties:
        object:
          const: list
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/Account'
    PostingSettings:
      type: object
      description: 'The account owner’s own posting rules, enforced like the platform caps (`account_limit_reached`): a daily maximum under the platform’s, a minimum gap between posts, and weekly slots that `scheduledFor: "next_slot"` fills.'
      properties:
        maxPostsPerDay:
          type: integer
          minimum: 1
          description: At most this many posts in any 24 hours, at most the platform’s cap.
        minGapMinutes:
          type: integer
          minimum: 1
          maximum: 1440
        timezone:
          type: string
          description: IANA zone of `slots`; the workspace’s when absent, else UTC.
        slots:
          type: array
          maxItems: 50
          items:
            type: object
            required:
            - day
            - time
            properties:
              day:
                type: integer
                minimum: 1
                maximum: 7
                description: 1 = Monday … 7 = Sunday.
              time:
                type: string
                pattern: ^([01]\d|2[0-3]):[0-5]\d$
                description: Local time, HH:MM.
    Account:
      type: object
      required:
      - object
      - id
      - workspaceId
      - platform
      - name
      - active
      - tokenHealth
      properties:
        object:
          const: account
        id:
          type: string
        workspaceId:
          type: string
        platform:
          type: string
        name:
          type: string
        handle:
          type:
          - string
          - 'null'
        accountType:
          type:
          - string
          - 'null'
        active:
          type: boolean
        tokenHealth:
          type: string
        connectedAt:
          type:
          - string
          - 'null'
          format: date-time
    AccountUpdate:
      type: object
      required:
      - posting
      properties:
        posting:
          type: object
          description: 'Fields to change; `null` removes one. `slots: []` or `null` removes the slots.'
          properties:
            maxPostsPerDay:
              type:
              - integer
              - 'null'
            minGapMinutes:
              type:
              - integer
              - 'null'
            timezone:
              type:
              - string
              - 'null'
            slots:
              type:
              - array
              - 'null'
              items:
                type: object
                properties:
                  day:
                    type: integer
                  time:
                    type: string
    PlatformPostsFetch:
      type: object
      additionalProperties: false
      properties:
        maxPosts:
          type: integer
          minimum: 1
          maximum: 25
          default: 10
    AccountDetail:
      allOf:
      - $ref: '#/components/schemas/Account'
      - type: object
        required:
        - settings
        properties:
          settings:
            type: array
            items:
              $ref: '#/components/schemas/SettingField'
          boards:
            type:
            - array
            - 'null'
            description: Pinterest only. Null when Pinterest refused the lookup.
            items:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
          boardsError:
            type: string
          reconnect:
            type: boolean
          dailyPostCap:
            type:
            - object
            - 'null'
            description: Posts this account may publish per rolling 24 hours on the owner's plan, and what is left. `remaining` subtracts both the posts published in the last 24 hours and those scheduled in the next 24, as the cap check does. `publishedLast24h` and `remaining` are absent when the count could not be read.
            properties:
              limit:
                type: integer
              windowHours:
                const: 24
              tier:
                type: string
                enum:
                - free
                - paid
              publishedLast24h:
                type: integer
              scheduledNext24h:
                type: integer
              remaining:
                type: integer
              platformLimit:
                type: integer
                description: The platform's maximum on the plan, when the owner set a lower `accountLimit`.
              accountLimit:
                type: integer
                description: The owner’s own daily maximum (`posting.maxPostsPerDay`); then it is `limit`.
              minGapMinutes:
                type: integer
                description: The owner’s minimum gap between this account’s posts.
          posting:
            oneOf:
            - $ref: '#/components/schemas/PostingSettings'
            - type: 'null'
          recentPosts:
            type: array
            description: 'With `include=recentPosts`: up to 15 of the account’s posts, its voice, text cut at 600 characters.'
            items:
              type: object
              properties:
                text:
                  type: string
                publishedAt:
                  type:
                  - string
                  - 'null'
                metrics:
                  type: object
          bestTimes:
            type: object
            description: 'With `include=bestTimes`: the suggested posting times the composer shows.'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer ak_...`. See /docs/api/keys.'