craaft Public API

openapi: 3.2.0
info:
  title: Craaft Public API
  version: 1.0.0
  description: 'Personal-access-token API for Craaft. See `docs/api.md` for the

    narrative guide, rate limits, and worked examples.'
  contact:
    name: Craaft
servers:
- url: https://craaft.io/api/v1
  description: Production
- url: http://localhost:8080/api/v1
  description: Local
security:
- bearerAuth: []
tags:
- name: Public
paths:
  /public/projects/{token}:
    parameters:
    - name: token
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Read-only public board snapshot (no auth)
      operationId: getPublicBoard
      description: 'Unauthenticated read of a board that has public sharing enabled. The

        share token is the access check; revoking sharing (or minting a new

        token) invalidates old links immediately. Returns a trimmed

        projection - no workspace, ownership, or private metadata.'
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicBoard'
        '404':
          description: No board with this share token (or sharing revoked)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Public
  /public/projects/{token}/background-image:
    parameters:
    - name: token
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Download a shared board's background image
      description: 'Unauthenticated, gated entirely by the share token in the URL -

        the same blob `/projects/{id}/background-image` serves to members.

        Bare `404` when the token is unknown or the board has no

        background set.'
      security: []
      responses:
        '200':
          description: Image bytes
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Unknown token, or no background set
      tags:
      - Public
      operationId: getPublicProjectsByTokenBackgroundImage
      x-operation-id-source: derived
components:
  schemas:
    PublicBoard:
      type: object
      description: 'Read-only snapshot returned by the unauthenticated

        `GET /public/projects/{token}` endpoint. A trimmed projection of the

        board: no workspace/ownership fields, no card metadata beyond

        priority + assignee.

        '
      required:
      - project
      - columns
      - cards
      properties:
        project:
          type: object
          required:
          - id
          - name
          - updatedAt
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
              maxLength: 200
            description:
              type: string
            backgroundImage:
              type: string
            backgroundColor:
              type: string
            colorScheme:
              type: string
            textColor:
              type: string
              enum:
              - dark
              - light
            updatedAt:
              type: string
              format: date-time
        columns:
          type: array
          items:
            type: object
            required:
            - key
            - title
            - position
            properties:
              key:
                type: string
              title:
                type: string
                maxLength: 80
              color:
                type: string
              position:
                type: number
                format: double
              isDone:
                type: boolean
        cards:
          type: array
          items:
            type: object
            required:
            - id
            - column
            - position
            - title
            properties:
              id:
                type: string
                format: uuid
              column:
                type: string
                description: column.key
              position:
                type: number
                format: double
              title:
                type: string
                maxLength: 500
              description:
                type: string
              priority:
                type: string
                enum:
                - low
                - medium
                - high
                - urgent
                nullable: true
              assignedUserId:
                type: string
                format: uuid
                nullable: true
              assignedUserName:
                type: string
                nullable: true
              assignedUserAvatarUrl:
                type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: craaft_session
      description: 'Browser session cookie (`__Host-craaft_session` in production,

        `craaft_session` in dev), set at sign-in. Not obtainable through

        this API - it''s here only so the handful of session-only routes

        below (the OAuth consent screen''s own endpoints, connected-apps

        management) can be marked accurately. They reject both bearer

        schemes with a 403.

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cra_<24 base64url chars>
      description: 'Two token schemes, same permissions. `cra_<24 base64url chars>` is a

        personal access token minted in Settings, doesn''t expire on its own,

        and is revoked from the same page. `cro_<32 base64url chars>` is an

        OAuth access token issued to an OAuth client (an MCP client such as

        Claude) via the authorization-code-with-PKCE flow; it expires after

        1 hour and the client refreshes it. Either token authenticates as

        the user who authorized it, with that user''s exact permissions.


        A token can be read-only: a personal access token created with

        access `read`, or an OAuth grant with scope `craaft:read`. A

        read-only token can send GET, HEAD and OPTIONS; any other method

        gets `403` with "this token is read-only; this request needs a

        token with read and write access", before the request is handled.


        A token can also be limited to chosen boards. Other boards then

        behave as if they don''t exist (`404`, or left out of lists), and

        `POST /projects`, `/imports`, `/members` and `/invitations` answer

        `403` with "this token is limited to some boards; this request

        needs a token for all boards".


        OAuth clients discover every endpoint they need - authorization,

        token, dynamic client registration, revocation - at

        `/.well-known/oauth-authorization-server` (RFC 8414); they don''t

        need to be told the URLs out of band.

        '