AgileHero Projects API

openapi: 3.2.0
info:
  title: AgileHero Projects API
  version: 0.1.3
  description: 'The AgileHero REST API lets your integration read and change the workspaces, projects, boards

    and cards of an AgileHero user who has authorized it. Every request acts as that user, with

    that user''s permissions. Base URL: `https://api.agilehero.io`. Every endpoint is under `/v0`. ## Version 0

    This API is version 0. It is complete and tested, and you can build on it today, but while it

    is being developed endpoints, fields and defaults may still change, and a change is not always

    backwards compatible. Each change is recorded in the changelog inside the OpenAPI document

    (`x-changelog`), with its date and version. When the API is declared stable it becomes version

    1 at `/v1`, and `/v0` keeps answering for a migration window that will be announced here. ## Authentication

    The API accepts OAuth 2.1 bearer access tokens only. Send `Authorization: Bearer `

    on every request. The authorization server is `https://mcp.agilehero.io`. Its metadata (RFC 8414) is at

    `https://mcp.agilehero.io/.well-known/oauth-authorization-server`. It supports the

    authorization-code grant with PKCE (S256, mandatory) and refresh tokens. Clients identify

    themselves with a Client ID Metadata Document URL as their `client_id`. This API''s own

    protected-resource metadata (RFC 9728) is at

    `https://api.agilehero.io/.well-known/oauth-protected-resource`. Request a token for this API with:

    - `resource=https://api.agilehero.io/v0` (RFC 8707), and

    - `scope=api:read`, or `scope=api:read api:write` to make changes. Every endpoint needs `api:read`. Endpoints that change data also need `api:write`. API scopes

    cannot be combined with the `mcp` scope in one request. A token for this API is not accepted by

    the AgileHero MCP server, and an MCP token is not accepted here. ## Permissions

    The token owner''s workspace role applies. Owners, admins and members can change the projects

    they can see. Observers cannot use the API at all: a workspace where the user is an observer is

    not listed by `/v0/me` or `/v0/workspaces`, and everything in it answers 404. Anything outside

    the user''s workspaces answers 404, and so does everything in a workspace that is being deleted

    or has been deleted, and in a project that is in the trash. Changes made through the API appear in

    AgileHero like the user''s own edits: collaborators see them live, watchers are notified, and the

    card history marks them as made through the API. ## Errors

    Every error has the same body: `{ "error": { "code", "message", "details"? } }`. | Status | code | When |

    |---|---|---|

    | 400 | `invalid_request` | The request body is not valid JSON. |

    | 401 | `unauthorized` | The token is missing, unknown, expired or revoked, or was issued for another resource. The `WWW-Authenticate` header carries a Bearer challenge with `resource_metadata`. |

    | 403 | `insufficient_scope` | The token lacks the scope the endpoint needs. `WWW-Authenticate` names it. |

    | 403 | `forbidden` | The user''s role does not allow the action, for example a member managing webhook endpoints. |

    | 404 | `not_found` | The resource does not exist or the user cannot access it. The two cases look the same. |

    | 422 | `validation_failed` | A parameter is invalid. `details` maps each parameter to messages. Nothing was changed. |

    | 429 | `rate_limited` | Too many requests. Wait `Retry-After` seconds. |


    A create answers 201. An update, a move or a delete answers 200. A delete answers

    `{ "data": { "id", "deleted": true } }`. ## Pagination

    Lists answer `{ "data": [...], "next_cursor": string | null }`. To get the next page, pass

    `next_cursor` back as `cursor`. A `null` cursor means the last page. Cursors are opaque and only

    valid for the list that issued them. Items come oldest first. While you page, every item is

    returned exactly once, even if items are added in between. `limit` defaults to 50, with a

    maximum of 200. Short lists (a board''s lists, a project''s labels, a card''s checklists and

    relations) are not paginated and always answer `next_cursor: null`.'
servers:
- url: https://api.agilehero.io
  description: Production. Every path below starts with /v0.
security:
- oauth2:
  - api:read
tags:
- name: Projects
  description: Projects, and the lists, labels and epics of a project.
paths:
  /v0/workspaces/{workspace_id}/projects:
    get:
      tags:
      - Projects
      operationId: listProjects
      summary: Projects of a workspace the token owner can see
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of projects.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v0/projects/{project_id}/lists:
    get:
      tags:
      - Projects
      operationId: listLists
      summary: The lists of a project's board
      description: 'Every list in board order: `to_do` lists, then `in_progress`, then `done`, by position inside each. Not paginated. The backlog is not a list; a card with a null `list` is in the backlog.'
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: The lists.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/List'
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Projects
      operationId: createList
      summary: Create a list
      security:
      - oauth2:
        - api:read
        - api:write
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCreate'
      responses:
        '201':
          $ref: '#/components/responses/ListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v0/lists/{list_id}:
    patch:
      tags:
      - Projects
      operationId: updateList
      summary: Rename a list or change its WIP limit
      security:
      - oauth2:
        - api:read
        - api:write
      parameters:
      - $ref: '#/components/parameters/ListId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListUpdate'
      responses:
        '200':
          $ref: '#/components/responses/ListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - Projects
      operationId: deleteList
      summary: Delete a list
      description: 'Says what happens to the cards on the list first: `move_to_backlog` (to the top of the backlog), `move_to_list` (to the top of `target_list_id`) or `delete_cards`. Send the parameters in the query string or a JSON body.'
      security:
      - oauth2:
        - api:read
        - api:write
      parameters:
      - $ref: '#/components/parameters/ListId'
      - name: card_action
        in: query
        required: true
        schema:
          type: string
          enum:
          - move_to_backlog
          - move_to_list
          - delete_cards
      - name: target_list_id
        in: query
        required: false
        description: The list that receives the cards, for `move_to_list`.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Deleted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v0/projects/{project_id}/labels:
    get:
      tags:
      - Projects
      operationId: listLabels
      summary: A project's labels
      description: Every label in display order. Not paginated.
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: The labels.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Label'
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Projects
      operationId: createLabel
      summary: Create a label
      description: The label goes last in the display order. Names are not required to be unique.
      security:
      - oauth2:
        - api:read
        - api:write
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelWrite'
      responses:
        '201':
          $ref: '#/components/responses/LabelResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v0/labels/{label_id}:
    patch:
      tags:
      - Projects
      operationId: updateLabel
      summary: Rename a label
      security:
      - oauth2:
        - api:read
        - api:write
      parameters:
      - $ref: '#/components/parameters/LabelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelWrite'
      responses:
        '200':
          $ref: '#/components/responses/LabelResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - Projects
      operationId: deleteLabel
      summary: Delete a label
      description: The label is removed from every card.
      security:
      - oauth2:
        - api:read
        - api:write
      parameters:
      - $ref: '#/components/parameters/LabelId'
      responses:
        '200':
          $ref: '#/components/responses/Deleted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v0/projects/{project_id}/epics:
    get:
      tags:
      - Projects
      operationId: listEpics
      summary: A project's epics
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of epics.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Epic'
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v0/epics/{epic_id}:
    get:
      tags:
      - Projects
      operationId: getEpic
      summary: One epic, with its description
      parameters:
      - name: epic_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The epic.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/EpicDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Project:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
        name:
          type: string
    List:
      type: object
      required:
      - id
      - name
      - category
      - position
      - limit
      - color
      - project
      - done
      - cards_count
      properties:
        id:
          type: string
        name:
          type: string
        category:
          type: string
          enum:
          - to_do
          - in_progress
          - done
        position:
          type: integer
          description: Order within the board (lists are grouped by category first).
        limit:
          type:
          - integer
          - 'null'
          description: The work-in-progress limit (guidance only; the app never blocks a move).
        color:
          type:
          - string
          - 'null'
        project:
          $ref: '#/components/schemas/Reference'
        done:
          type: boolean
          description: Whether cards in this list count as finished (the `done` category).
        cards_count:
          type: integer
    ListUpdate:
      type: object
      minProperties: 1
      properties:
        name:
          type: string
          minLength: 1
        limit:
          type:
          - integer
          - 'null'
          minimum: 1
          description: null removes the limit.
    ListCreate:
      type: object
      required:
      - name
      - category
      properties:
        name:
          type: string
          minLength: 1
        category:
          type: string
          enum:
          - to_do
          - in_progress
          - done
        limit:
          type:
          - integer
          - 'null'
          minimum: 1
        position:
          type: integer
          minimum: 0
          description: Order within the board; omitted, the list goes last in its category.
    Epic:
      type: object
      required:
      - id
      - number
      - name
      - color
      - description_present
      - project
      - assignees
      - start_date
      - end_date
      - created_at
      - updated_at
      properties:
        id:
          type: string
        number:
          type: integer
        name:
          type: string
        color:
          type: string
        description_present:
          type: boolean
        project:
          $ref: '#/components/schemas/Reference'
        assignees:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        start_date:
          type:
          - string
          - 'null'
          format: date
        end_date:
          type:
          - string
          - 'null'
          format: date
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    EpicDetail:
      allOf:
      - $ref: '#/components/schemas/Epic'
      - type: object
        required:
        - description_markdown
        properties:
          description_markdown:
            type:
            - string
            - 'null'
            description: The description as Markdown (see "Rich text"); null when there is none.
    LabelWrite:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
    Reference:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
        name:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - unauthorized
              - insufficient_scope
              - forbidden
              - not_found
              - validation_failed
              - rate_limited
            message:
              type: string
            details:
              type: object
              description: Parameter name to a list of messages (validation_failed only).
              additionalProperties:
                type: array
                items:
                  type: string
    Label:
      type: object
      required:
      - id
      - name
      - project
      - position
      properties:
        id:
          type: string
        name:
          type: string
        project:
          $ref: '#/components/schemas/Reference'
        position:
          type: integer
          description: Display order.
  responses:
    ValidationFailed:
      description: A parameter is invalid; nothing was changed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: validation_failed
              message: The request parameters are invalid.
              details:
                title:
                - can't be blank
    RateLimited:
      description: Too many requests.
      headers:
        Retry-After:
          description: Seconds until the limit resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: '`insufficient_scope` (the token lacks the scope; `WWW-Authenticate` carries `error="insufficient_scope", scope="…"`) or `forbidden` (the user''s role does not allow it).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or unusable access token.
      headers:
        WWW-Authenticate:
          description: '`Bearer realm="AgileHero API", resource_metadata="https://api.agilehero.io/.well-known/oauth-protected-resource"`, plus `error="invalid_token"` when a token was presented.'
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Deleted:
      description: The resource was deleted.
      content:
        application/json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                type: object
                required:
                - id
                - deleted
                properties:
                  id:
                    type: string
                  deleted:
                    type: boolean
                    enum:
                    - true
    ListResponse:
      description: The list.
      content:
        application/json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                $ref: '#/components/schemas/List'
    NotFound:
      description: The resource does not exist or the token owner cannot access it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request body could not be parsed (`invalid_request`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    LabelResponse:
      description: The label.
      content:
        application/json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                $ref: '#/components/schemas/Label'
  parameters:
    ListId:
      name: list_id
      in: path
      required: true
      schema:
        type: string
    ProjectId:
      name: project_id
      in: path
      required: true
      schema:
        type: string
    WorkspaceId:
      name: workspace_id
      in: path
      required: true
      schema:
        type: string
    LabelId:
      name: label_id
      in: path
      required: true
      schema:
        type: string
    Cursor:
      name: cursor
      in: query
      required: false
      description: The `next_cursor` of the previous page.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Page size, 1 to 200.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  securitySchemes:
    oauth2:
      type: oauth2
      description: Authorization code with PKCE (S256). Send `resource=https://api.agilehero.io/v0` on the authorization and token requests.
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.agilehero.io/oauth/authorize
          tokenUrl: https://mcp.agilehero.io/oauth/token
          refreshUrl: https://mcp.agilehero.io/oauth/token
          scopes:
            api:read: Read the workspaces, projects and cards the user can access.
            api:write: Change the projects and cards the user can change, and manage webhook endpoints.
x-changelog:
- date: '2026-10-05'
  version: 0.1.3
  title: Free-plan rate limit
  description: Requests to a Free workspace's resources are limited to 150 per minute per access token; trial and Pro workspaces keep 600. The limit answers 429 `rate_limited` with `Retry-After`, as before.
- date: '2026-10-01'
  version: 0.1.2
  title: Cards by epic
  description: '`GET /v0/projects/{project_id}/cards` takes `epic_id` to list the cards of one epic across the backlog and every list.'
- date: '2026-10-01'
  version: 0.1.1
  title: Observers and deleted workspaces
  description: 'Observers can no longer use the API: a workspace where the token owner is an observer is no longer listed by `/v0/me` and `/v0/workspaces`, and every request into it answers 404 (reads used to be allowed). Everything in a deleted workspace now answers 404 too.'
- date: '2026-10-01'
  version: 0.1.0
  title: Version 0
  description: 'The API ships as version 0: every path moved from `/v1` to `/v0`, and the token resource is now `https://api.agilehero.io/v0`. Endpoints, scopes, authentication and responses are unchanged. Version 0 is still being developed and can change; it becomes version 1 at `/v1` when it is declared stable.'
- date: '2026-09-26'
  version: 0.0.2
  title: v0 writes
  description: 'Writes for cards (create, update, move, delete), lists, labels, card labels, card assignees, card relations, card checklists, checklist items and card comments, with reads for each. New read-only endpoints for epics and workspace members. `GET /v0/cards/{card_id}` adds `description_markdown`, `checklists`, `relations` and `comments_count`. Webhook endpoints: subscribe, list, sample and unsubscribe (workspace owners and admins).'
- date: '2026-09-26'
  version: 0.0.1
  title: v0 reads
  description: The token owner, workspaces, projects and cards, read-only.