openapi: 3.0.3
info:
  title: Aptly App Schema API
  version: '1.0'
  description: 'The Aptly API lets you read and write cards on any Aptly board from external systems.


    All requests require an API key passed as the `x-token` header.

    API keys are scoped to your company and work across all boards.

    '
servers:
- url: https://core-api.getaptly.com
  description: Production
security:
- ApiKeyHeader: []
tags:
- name: Schema
paths:
  /api/schema/{boardId}:
    get:
      summary: Get board schema
      description: 'Returns the list of fields defined on the board. Always fetch the schema first so

        you know which field keys to use when reading or writing card data.

        '
      operationId: getSchema
      tags:
      - Schema
      security:
      - ApiKeyHeader: []
      - DelegateToken: []
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: string
        description: The board's UUID (`aptlet.uuid`).
      responses:
        '200':
          description: Array of field definitions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SchemaField'
              example:
              - key: abc123
                label: Tenant Name
                type: text
              - key: def456
                label: Move-in Date
                type: date
              - key: ghi789
                label: Monthly Rent
                type: money
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API access is disabled for this board.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Board not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SchemaField:
      type: object
      properties:
        key:
          type: string
          description: Field UUID — use this as the key when reading/writing card data.
        label:
          type: string
          description: Human-readable field name.
        type:
          type: string
          description: Field type (e.g. text, date, money, multiselect, etc.)
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-token
    DelegateToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Delegate token issued by the platform. Format: `DelegateToken <token>`'
    PartnerBearer:
      type: http
      scheme: bearer
      description: 'Partner token. Format: `Authorization: Bearer <token>`'