Antwork Workspaces API

openapi: 3.2.0
info:
  title: Antwork Workspaces 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: Workspaces
paths:
  /workspaces:
    get:
      operationId: listWorkspaces
      summary: Every workspace the key owner has, oldest first
      description: 'Scope: `read`.


        Docs: https://antwork.io/docs/api/list-workspaces'
      x-antwork-scope: read
      externalDocs:
        url: https://antwork.io/docs/api/list-workspaces
      responses:
        '200':
          description: Every usable workspace; not paged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceList'
        '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:
      - Workspaces
    post:
      operationId: createWorkspace
      summary: Create a workspace
      description: 'Scope: `write`.


        Docs: https://antwork.io/docs/api/create-workspace'
      x-antwork-scope: write
      externalDocs:
        url: https://antwork.io/docs/api/create-workspace
      parameters:
      - 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:
              type: object
              required:
              - name
              additionalProperties: false
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 60
                website:
                  type: string
                  description: https URL; a bare host gets https://.
      responses:
        '201':
          description: The new workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: 'The request was refused. Codes: `invalid_body`, `invalid_name`, `invalid_website`.'
          x-error-codes:
          - invalid_body
          - invalid_name
          - invalid_website
          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'
        '402':
          description: 'Refused. Codes: `workspace_limit`.'
          x-error-codes:
          - workspace_limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The key cannot do this. Codes: `account_under_review`, `insufficient_scope`, `subscription_inactive`.'
          x-error-codes:
          - account_under_review
          - insufficient_scope
          - subscription_inactive
          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:
      - Workspaces
  /workspaces/{workspaceId}:
    patch:
      operationId: updateWorkspace
      summary: Change a workspace's name, website, logo or settings
      description: 'Only the fields sent change; "" or null clears website or logoUrl, "" clears timezone. Bumps brandVersion.


        Scope: `write`.


        Docs: https://antwork.io/docs/api/update-workspace'
      x-antwork-scope: write
      externalDocs:
        url: https://antwork.io/docs/api/update-workspace
      parameters:
      - name: workspaceId
        in: path
        required: true
        description: A workspace id.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              additionalProperties: false
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 60
                website:
                  type:
                  - string
                  - 'null'
                  description: https URL, or "" / null to clear.
                logoUrl:
                  type:
                  - string
                  - 'null'
                  description: https URL, or "" / null to clear.
                timezone:
                  type: string
                  description: IANA timezone for scheduling, e.g. "Europe/Madrid"; "" clears it.
                preferredTimes:
                  type: array
                  items:
                    type: string
                    pattern: ^\d{2}:\d{2}$
                  description: Preferred posting times as HH:MM.
                tagOutboundLinks:
                  type: boolean
                  description: Append UTM parameters to links on the workspace's own website when a post publishes.
      responses:
        '200':
          description: The workspace as saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: 'The request was refused. Codes: `invalid_body`, `invalid_name`, `invalid_website`, `invalid_logo_url`, `invalid_timezone`, `invalid_preferred_times`, `invalid_tag_outbound_links`.'
          x-error-codes:
          - invalid_body
          - invalid_name
          - invalid_website
          - invalid_logo_url
          - invalid_timezone
          - invalid_preferred_times
          - invalid_tag_outbound_links
          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: `workspace_not_found`.'
          x-error-codes:
          - workspace_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:
      - Workspaces
  /workspaces/{workspaceId}/connect-urls:
    get:
      operationId: getConnectUrls
      summary: A link per platform that connects or reconnects an account to this workspace
      description: 'OAuth happens in the browser of whoever opens the link. Links work for 15 minutes (`expiresAt`).


        Scope: `read`.


        Docs: https://antwork.io/docs/api/connect-urls'
      x-antwork-scope: read
      externalDocs:
        url: https://antwork.io/docs/api/connect-urls
      parameters:
      - name: workspaceId
        in: path
        required: true
        description: A workspace id.
        schema:
          type: string
      responses:
        '200':
          description: The links.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectUrls'
        '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: `workspace_not_found`.'
          x-error-codes:
          - workspace_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:
      - Workspaces
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.'
    Workspace:
      type: object
      required:
      - object
      - id
      - name
      - brandVersion
      properties:
        object:
          const: workspace
        id:
          type: string
        name:
          type: string
        website:
          type:
          - string
          - 'null'
        logoUrl:
          type:
          - string
          - 'null'
        timezone:
          type:
          - string
          - 'null'
        preferredTimes:
          type: array
          items:
            type: string
            pattern: ^\d{2}:\d{2}$
          description: Preferred posting times, HH:MM in `timezone`.
        tagOutboundLinks:
          type: boolean
          description: UTM tags on links to the workspace's own website when a post publishes.
        brandVersion:
          type: integer
          description: Bumped when the identity or settings change.
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
    WorkspaceList:
      type: object
      required:
      - object
      - workspaces
      properties:
        object:
          const: list
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/Workspace'
    ConnectUrls:
      type: object
      required:
      - object
      - workspaceId
      - urls
      - alreadyConnected
      - notConnected
      - expiresAt
      properties:
        object:
          const: connect_urls
        workspaceId:
          type: string
        urls:
          type: object
          additionalProperties:
            type: string
          description: Keyed by platform.
        alreadyConnected:
          type: array
          items:
            type: string
        notConnected:
          type: array
          items:
            type: string
        requirements:
          type: object
          additionalProperties:
            type: string
          description: What an account must be for its connect to succeed.
        expiresAt:
          type: string
          format: date-time
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer ak_...`. See /docs/api/keys.'