Antwork Campaigns API

openapi: 3.2.0
info:
  title: Antwork Campaigns 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: Campaigns
paths:
  /campaigns/{campaignId}/publish:
    post:
      operationId: publishCampaign
      summary: Send every post of a campaign now; failed ones are retried
      description: 'Each post of the campaign on its own: one refused post does not hold the others back. At most 10 posts. Answers like POST /posts: a `post_result` per post, 202 when any was accepted, 400 with the first reason when none was. Poll each post with GET /posts/{postId}. TikTok posts take the user''s choices in `tiktokSettings`, keyed by post id; one without them is rejected with `tiktok_choices_needed` and its `tiktokChoices`.


        Scope: `publish`.


        Docs: https://antwork.io/docs/api/send-post'
      x-antwork-scope: publish
      externalDocs:
        url: https://antwork.io/docs/api/send-post
      parameters:
      - name: campaignId
        in: path
        required: true
        description: A campaign id, as POST /posts returns it.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: A retry with the same key and body replays the first answer instead of acting twice. See /docs/api/idempotency.
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignPublishBody'
      responses:
        '202':
          description: At least one post was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBatch'
        '400':
          description: 'The request was refused. Codes: `invalid_option`, `too_many_posts`.'
          x-error-codes:
          - invalid_option
          - too_many_posts
          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: `campaign_not_found`.'
          x-error-codes:
          - campaign_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'Conflict. Codes: `idempotency_in_flight`.'
          x-error-codes:
          - idempotency_in_flight
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Unprocessable. Codes: `idempotency_key_reused`.'
          x-error-codes:
          - idempotency_key_reused
          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:
      - Campaigns
  /campaigns/{campaignId}/schedule:
    post:
      operationId: scheduleCampaign
      summary: Schedule every post of a campaign at one time
      description: 'Each post of the campaign on its own: one refused post does not hold the others back. At most 10 posts. Answers like POST /posts: a `post_result` per post, 202 when any was accepted, 400 with the first reason when none was. Poll each post with GET /posts/{postId}. TikTok posts take the user''s choices in `tiktokSettings`, keyed by post id; one without them is rejected with `tiktok_choices_needed` and its `tiktokChoices`.


        Scope: `publish`.


        Docs: https://antwork.io/docs/api/send-post'
      x-antwork-scope: publish
      externalDocs:
        url: https://antwork.io/docs/api/send-post
      parameters:
      - name: campaignId
        in: path
        required: true
        description: A campaign id, as POST /posts returns it.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: A retry with the same key and body replays the first answer instead of acting twice. See /docs/api/idempotency.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignScheduleBody'
      responses:
        '202':
          description: At least one post was scheduled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBatch'
        '400':
          description: 'The request was refused. Codes: `invalid_body`, `invalid_option`, `invalid_scheduled_for`, `scheduled_for_in_past`, `scheduled_for_too_far`, `too_many_posts`.'
          x-error-codes:
          - invalid_body
          - invalid_option
          - invalid_scheduled_for
          - scheduled_for_in_past
          - scheduled_for_too_far
          - too_many_posts
          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: `campaign_not_found`.'
          x-error-codes:
          - campaign_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'Conflict. Codes: `idempotency_in_flight`.'
          x-error-codes:
          - idempotency_in_flight
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Unprocessable. Codes: `idempotency_key_reused`.'
          x-error-codes:
          - idempotency_key_reused
          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:
      - Campaigns
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
    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.'
    PostResult:
      type: object
      required:
      - object
      - id
      - accountId
      - platform
      - status
      - reason
      - message
      - readiness
      - editUrl
      - settingsUrl
      properties:
        object:
          const: post_result
        id:
          type:
          - string
          - 'null'
          description: Null when the target was rejected before anything was written.
        accountId:
          type:
          - string
          - 'null'
        platform:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - accepted
          - rejected
          - failed
        reason:
          type:
          - string
          - 'null'
          description: A rejection reason from /docs/api/errors.
        message:
          type:
          - string
          - 'null'
        readiness:
          oneOf:
          - $ref: '#/components/schemas/PostReadiness'
          - type: 'null'
          description: What the post still needs before it can publish. Null when nothing was written.
        editUrl:
          type:
          - string
          - 'null'
          description: The post in the Antwork composer.
        settingsUrl:
          type:
          - string
          - 'null'
          description: The post in the composer with its settings open.
        retried:
          type: boolean
          description: 'Campaign publish only: a failed post was requeued (its retry).'
        pendingApproval:
          type: boolean
          description: 'Accepted for approval, not for publishing: the workspace requires approval, so the post is `pending_approval` and goes out once a person approves it in the Antwork app.'
        similarRecent:
          type: array
          description: Near-duplicates of this post on the same account from the last 30 days (shared distinct words, Jaccard ≥ 0.6), most similar first, at most 3. A hint, never a refusal.
          items:
            type: object
            properties:
              postId:
                type: string
              status:
                type: string
              at:
                type:
                - string
                - 'null'
              similarity:
                type: number
              excerpt:
                type: string
        tiktokChoices:
          $ref: '#/components/schemas/TikTokChoices'
        problems:
          type: array
          items:
            type: object
          description: With `tiktok_choices_needed` after settings were sent.
        tagChecks:
          type: array
          description: 'Instagram posts with `photo_tag` userTags: each handle looked up on Instagram. `found` carries the profile; `unchecked` means Instagram would not say (personal and age-gated accounts cannot be looked up), not that the handle is wrong.'
          items:
            type: object
            required:
            - username
            - status
            properties:
              username:
                type: string
              status:
                type: string
                enum:
                - found
                - unchecked
              name:
                type:
                - string
                - 'null'
              pictureUrl:
                type:
                - string
                - 'null'
    TikTokSettings:
      oneOf:
      - $ref: '#/components/schemas/TikTokAnswers'
      - $ref: '#/components/schemas/TikTokUseLast'
      description: 'The user''s choices for one TikTok post: each answer, or `useLast` once they said yes to the `lastUsed` settings offered.'
    PostBatch:
      type: object
      required:
      - object
      - campaignId
      - posts
      properties:
        object:
          const: post_batch
        campaignId:
          type:
          - string
          - 'null'
        posts:
          type: array
          items:
            $ref: '#/components/schemas/PostResult'
    TikTokAnswers:
      type: object
      description: The user's own choices for one TikTok post, asked from the `tiktokChoices` of a `tiktok_choices_needed` refusal. Checked against the creator's live options; never chosen for the user.
      required:
      - privacyLevel
      - allowComment
      - commercialContent
      - userConsented
      properties:
        privacyLevel:
          type: string
          description: One of `tiktokChoices.privacyLevel.options`. No default.
        allowComment:
          type: boolean
        allowDuet:
          type: boolean
          description: Required for a video.
        allowStitch:
          type: boolean
          description: Required for a video.
        commercialContent:
          type: object
          required:
          - enabled
          properties:
            enabled:
              type: boolean
            yourBrand:
              type: boolean
              description: Labelled "Promotional content".
            brandedContent:
              type: boolean
              description: Labelled "Paid partnership". Not with `SELF_ONLY`.
        aiGenerated:
          type: boolean
        userConsented:
          const: true
          description: The user agreed to the declaration in `tiktokChoices.declaration`.
    CampaignPublishBody:
      type: object
      properties:
        tiktokSettings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TikTokSettings'
          description: Each TikTok post's settings, keyed by post id.
    PostReadiness:
      type: object
      required:
      - characterCount
      - characterLimit
      - overLimit
      - mediaRequired
      - settingsRequired
      - publishBlocker
      properties:
        characterCount:
          type: integer
        characterLimit:
          type:
          - integer
          - 'null'
        overLimit:
          type: boolean
        mediaRequired:
          type: boolean
        settingsRequired:
          type: boolean
          description: A setting only the account owner picks (TikTok audience) is unset.
        publishBlocker:
          type:
          - string
          - 'null'
          description: The rejection reason a publish would get now, or null.
    CampaignScheduleBody:
      type: object
      required:
      - scheduledFor
      properties:
        scheduledFor:
          type: string
          format: date-time
          description: 'When to publish: in the future, at most 30 days ahead.'
        tiktokSettings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TikTokSettings'
          description: Each TikTok post's settings, keyed by post id.
    TikTokUseLast:
      type: object
      description: The account's last answers (`tiktokChoices.lastUsed`), re-checked against the creator's live options. Send only after the user said yes to them for this post; nothing stored applies without it.
      required:
      - useLast
      - userConsented
      additionalProperties: false
      properties:
        useLast:
          const: true
        userConsented:
          const: true
          description: The user agreed to their usual settings and the declaration for this post.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer ak_...`. See /docs/api/keys.'