Antwork Usage API

openapi: 3.2.0
info:
  title: Antwork Usage 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: Usage
paths:
  /usage:
    get:
      operationId: getUsage
      summary: 'Your plan and quota position: posts this cycle and workspaces'
      description: 'The numbers MCP list_workspaces reports, from the functions the enforcement uses. Daily per-account caps are on GET /accounts/{id}.


        Scope: `read`.


        Docs: https://antwork.io/docs/api/usage'
      x-antwork-scope: read
      externalDocs:
        url: https://antwork.io/docs/api/usage
      responses:
        '200':
          description: The usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '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:
      - Usage
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.'
    Usage:
      type: object
      required:
      - object
      - plan
      - posts
      - workspaces
      properties:
        object:
          const: usage
        plan:
          type: string
        posts:
          type: object
          description: 'Posts committed this billing cycle. With `unlimited: true` nothing is counted: `used` is 0, `limit` and `remaining` null.'
          properties:
            used:
              type: integer
            limit:
              type:
              - integer
              - 'null'
            remaining:
              type:
              - integer
              - 'null'
            unlimited:
              type: boolean
            cycleStart:
              type: string
              format: date-time
            cycleEnd:
              type: string
              format: date-time
            usageUnavailable:
              const: true
              description: The count could not be taken; `used` is unknown.
        workspaces:
          type: object
          properties:
            used:
              type: integer
            limit:
              type:
              - integer
              - 'null'
            remaining:
              type:
              - integer
              - 'null'
            unlimited:
              type: boolean
        billing:
          type: object
          description: Where to change the plan and what is time-limited or scheduled. Present for accounts on the Free/Pro/Business/Scale/Agency plans.
          required:
          - billingUrl
          properties:
            billingUrl:
              type: string
              format: uri
              description: 'The plan page: upgrade, switch, cancel, claim the founding offer.'
            interval:
              enum:
              - month
              - year
              description: A paid plan's billing period.
            renewsAt:
              type: string
              format: date-time
              description: When a paid plan renews, or ends if `cancelsAtPeriodEnd`.
            cancelsAtPeriodEnd:
              const: true
              description: The paid plan moves to Free at `renewsAt`.
            scheduledChange:
              type: object
              description: A downgrade waiting for the renewal.
              properties:
                plan:
                  type: string
                interval:
                  enum:
                  - month
                  - year
                at:
                  type:
                  - string
                  - 'null'
                  format: date-time
            foundingOffer:
              type: object
              description: '`percentOff` off the first year of any yearly plan, bought before `endsAt`. Only while the account can still take it.'
              properties:
                percentOff:
                  type: integer
                endsAt:
                  type: string
                  format: date-time
            unlimitedPostsUntil:
              type: string
              format: date-time
              description: Unlimited posts end then; Free allows `postsPerMonthAfter` a month after.
            postsPerMonthAfter:
              type: integer
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer ak_...`. See /docs/api/keys.'