Antwork Media API

openapi: 3.2.0
info:
  title: Antwork Media 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: Media
paths:
  /media:
    get:
      operationId: listMedia
      summary: The workspace media library, newest first
      description: 'Scope: `read`.


        Docs: https://antwork.io/docs/api/list-media'
      x-antwork-scope: read
      externalDocs:
        url: https://antwork.io/docs/api/list-media
      parameters:
      - name: workspaceId
        in: query
        required: false
        description: Required when the account has more than one workspace.
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: '`image`, `video` or `document` (`pdf` is accepted for `document`).'
        schema:
          type: string
          enum:
          - image
          - video
          - document
          - pdf
      - name: limit
        in: query
        required: false
        description: Page size, 1 to 100.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: cursor
        in: query
        required: false
        description: '`nextCursor` from the previous page.'
        schema:
          type: string
      responses:
        '200':
          description: One page of media.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaList'
        '400':
          description: 'The request was refused. Codes: `workspace_required`, `invalid_filter`, `invalid_limit`, `invalid_cursor`.'
          x-error-codes:
          - workspace_required
          - invalid_filter
          - invalid_limit
          - invalid_cursor
          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: `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:
      - Media
    post:
      operationId: createMedia
      summary: 'Add a file to the media library: from a public link, or a one-time address to…'
      description: '`upload: {filename, mimeType, size}` answers a one-time `uploadUrl` (10 minutes to start, one use) on the endpoint MCP `add_media(upload=…)` uses: one PUT of the bytes stores, registers and attaches the file. Otherwise the server fetches `url` (public http(s) hosts on the default port only; every redirect re-checked), reads the type from the bytes and stores it. PNG, JPEG, GIF, WebP, AVIF up to 10 MB; MP4, MOV, WebM and PDF up to 100 MB. `attachToPostIds` appends it to those posts. Each failure carries the code MCP `add_media(url=…)` gives it. At most 20 links per key per 10 minutes. A file that would take the workspace owner''s media storage (across all their workspaces) past their plan''s limit is refused before it is stored, `storage_limit_reached`; nothing already stored is touched.


        Scope: `media`.


        Docs: https://antwork.io/docs/api/upload-media'
      x-antwork-scope: media
      externalDocs:
        url: https://antwork.io/docs/api/upload-media
      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:
              $ref: '#/components/schemas/MediaCreate'
      responses:
        '201':
          description: '`url`: stored, and attached where asked. `upload`: the address to PUT the file to.'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/MediaCreated'
                - $ref: '#/components/schemas/MediaUpload'
        '400':
          description: 'The request was refused. Codes: `invalid_body`, `workspace_required`, `workspace_not_found`, `remote_http_error`, `not_a_file`, `unsupported_type`, `too_large`, `empty_file`, `blocked_url`, `fetch_timeout`, `fetch_failed`.'
          x-error-codes:
          - invalid_body
          - workspace_required
          - workspace_not_found
          - remote_http_error
          - not_a_file
          - unsupported_type
          - too_large
          - empty_file
          - blocked_url
          - fetch_timeout
          - fetch_failed
          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: `storage_limit_reached`.'
          x-error-codes:
          - storage_limit_reached
          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: `post_not_found`.'
          x-error-codes:
          - post_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: `url_ingest_rate_limited`, `rate_limit_burst`, `rate_limit_daily`.'
          x-error-codes:
          - url_ingest_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: `storage_failed`, `internal_error`.'
          x-error-codes:
          - storage_failed
          - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Media
  /media/{mediaId}:
    delete:
      operationId: deleteMedia
      summary: Remove a file from the media library. Refused while a post uses it
      description: 'Scope: `media`.


        Docs: https://antwork.io/docs/api/delete-media'
      x-antwork-scope: media
      externalDocs:
        url: https://antwork.io/docs/api/delete-media
      parameters:
      - name: mediaId
        in: path
        required: true
        description: A media id from GET /media.
        schema:
          type: string
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaDeleted'
        '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: `media_not_found`.'
          x-error-codes:
          - media_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'Conflict. Codes: `media_in_use`.'
          x-error-codes:
          - media_in_use
          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:
      - Media
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
    MediaUpload:
      type: object
      required:
      - object
      - uploadUrl
      - method
      - expiresAt
      - attachesTo
      - maxBytes
      properties:
        object:
          const: media_upload
        uploadUrl:
          type: string
          description: PUT the raw bytes here, once. Its JSON answer has the `mediaId` and `url`.
        method:
          const: PUT
        expiresAt:
          type: string
          format: date-time
          description: Start the upload before this; a long upload may finish after it.
        attachesTo:
          type: array
          items:
            type: string
          description: The posts the file is appended to when it lands.
        maxBytes:
          type: integer
    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.'
    MediaCreate:
      type: object
      description: Exactly one of `url` and `upload`.
      properties:
        url:
          type: string
          description: A public link to the image, video or PDF itself; the server fetches it.
        upload:
          type: object
          required:
          - filename
          - mimeType
          - size
          description: 'A file you hold: the answer is a one-time `uploadUrl` to PUT its bytes to.'
          properties:
            filename:
              type: string
            mimeType:
              type: string
              enum:
              - image/png
              - image/jpeg
              - image/gif
              - image/webp
              - image/avif
              - video/mp4
              - video/quicktime
              - video/webm
              - application/pdf
            size:
              type: integer
              description: Bytes. Images up to 10 MB, video and PDF up to 1 GB.
        workspaceId:
          type: string
          description: Required when the account has more than one workspace.
        attachToPostIds:
          type: array
          maxItems: 20
          items:
            type: string
          description: Posts to append the file to.
    Media:
      type: object
      required:
      - object
      - id
      - workspaceId
      - url
      - name
      - type
      properties:
        object:
          const: media
        id:
          type: string
        workspaceId:
          type: string
        url:
          type: string
          description: What `media` on a post takes.
        name:
          type: string
        type:
          type: string
          enum:
          - image
          - video
          - document
        size:
          type: integer
        durationSec:
          type:
          - number
          - 'null'
        uploadedAt:
          type:
          - string
          - 'null'
          format: date-time
    MediaCreated:
      allOf:
      - $ref: '#/components/schemas/Media'
      - type: object
        properties:
          attached:
            type: array
            items:
              type: string
            description: 'With `attachToPostIds`: the posts it was added to.'
          notAttached:
            type: array
            items:
              type: object
              properties:
                postId:
                  type: string
                reason:
                  type: string
                message:
                  type: string
            description: 'With `attachToPostIds`: the posts it was not added to, and why (a published post).'
    MediaList:
      type: object
      required:
      - object
      - media
      - nextCursor
      properties:
        object:
          const: list
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        nextCursor:
          type:
          - string
          - 'null'
    MediaDeleted:
      type: object
      required:
      - object
      - id
      - deleted
      properties:
        object:
          const: media_deleted
        id:
          type: string
        deleted:
          const: true
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer ak_...`. See /docs/api/keys.'