twelfth-ai Workspace API

openapi: 3.2.0
info:
  title: Twelfth REST Workspace API
  version: 1.0.0
  description: 'A deliberately small resource API for server-side Twelfth integrations. It starts with workspace identity and current task reads; new resources are added only after their contracts and permissions are ready.


    **Authentication.** Send a workspace API key as `Authorization: Bearer `. Give each server, script or automation its own labelled key and never expose a key in browser code.


    **Errors.** Every error is `application/problem+json` (RFC 9457), with a stable machine-readable `code` and a recovery `hint`.


    **Compatibility.** Paths are stable and unversioned. Published operations evolve additively: existing paths, fields and documented error codes remain supported.


    **Rate limits.** Responses carry `RateLimit-*` headers; a `429` also carries `Retry-After`.'
  contact:
    name: Twelfth AI developer enquiries
    email: hello@twelfth.ai
    url: https://twelfth.ai/developers
servers:
- url: https://api.twelfth.ai
  description: Twelfth production API
tags:
- name: Workspace
paths:
  /workspace:
    get:
      operationId: getWorkspace
      summary: Get the workspace
      description: Returns the identity and operating defaults of the workspace attached to the API key. Use these timezone, currency and country values when interpreting dates and money from later resources.
      security:
      - workspaceApiKey: []
      responses:
        '200':
          description: The workspace attached to the API key.
          headers:
            RateLimit-Limit:
              description: Request quota for the current window.
              schema:
                type: integer
                example: 120
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
                example: 119
            RateLimit-Reset:
              description: Seconds until the current window resets.
              schema:
                type: integer
                example: 47
            RateLimit-Policy:
              description: The quota policy, as `<limit>;w=<window-seconds>`.
              schema:
                type: string
                example: 120;w=60
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceResponse'
        '401':
          description: The workspace API key is missing, invalid or revoked.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: The key no longer refers to an available workspace.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          description: The resource is read-only.
          headers:
            Allow:
              description: Permitted methods.
              schema:
                type: string
                example: GET, HEAD, OPTIONS
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded. Retry after the window resets.
          headers:
            RateLimit-Limit:
              description: Request quota for the current window.
              schema:
                type: integer
                example: 120
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
                example: 119
            RateLimit-Reset:
              description: Seconds until the current window resets.
              schema:
                type: integer
                example: 47
            RateLimit-Policy:
              description: The quota policy, as `<limit>;w=<window-seconds>`.
              schema:
                type: string
                example: 120;w=60
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                example: 47
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      tags:
      - Workspace
components:
  schemas:
    WorkspaceResponse:
      type: object
      required:
      - workspace
      properties:
        workspace:
          $ref: '#/components/schemas/Workspace'
      additionalProperties: true
    Workspace:
      type: object
      required:
      - id
      - name
      - slug
      - timezone
      - currencyCode
      - countryCode
      properties:
        id:
          type: string
          description: Stable workspace identifier.
          example: org_01JABCDEFGHJKMNPQRSTVWXYZ
        name:
          type: string
          description: Display name.
          example: Northstar Retail
        slug:
          type: string
          description: Human-readable workspace slug.
          example: northstar-retail
        timezone:
          type:
          - string
          - 'null'
          description: IANA timezone used for business dates.
          example: Australia/Melbourne
        currencyCode:
          type:
          - string
          - 'null'
          description: ISO 4217 reporting currency.
          example: AUD
        countryCode:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2 country code.
          example: AU
      additionalProperties: true
    Problem:
      type: object
      description: A structured, machine-readable error (RFC 9457 problem detail).
      required:
      - type
      - title
      - status
      - code
      - detail
      - hint
      properties:
        type:
          type: string
          format: uri-reference
          default: about:blank
        title:
          type: string
          description: Short, human-readable summary.
        status:
          type: integer
          description: HTTP status code.
          example: 401
        code:
          type: string
          enum:
          - not_found
          - method_not_allowed
          - rate_limited
          - unauthorized
          - workspace_not_found
          - internal_error
          description: Stable error code for programmatic handling.
          example: unauthorized
        detail:
          type: string
          description: Explanation specific to this occurrence.
        hint:
          type: string
          description: How to resolve or work around the error.
      additionalProperties: true
  securitySchemes:
    workspaceApiKey:
      type: http
      scheme: bearer
      description: Workspace API key generated by a Twelfth workspace owner or admin.
externalDocs:
  description: Twelfth developer API guide
  url: https://twelfth.ai/docs/developers/
x-api-lifecycle:
  versioning: Stable, unversioned URL paths. A path names a resource or capability, never a release number.
  deprecationPolicy: Published paths, methods, fields and documented error codes remain backwards compatible. Twelfth may add optional fields, resources and operations. Deprecated contract elements remain supported; a security or legal emergency that makes continued support impossible is announced at https://twelfth.ai/developers and signalled with Deprecation and Sunset headers where practical.