AgileHero Account API

openapi: 3.2.0
info:
  title: AgileHero Account 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: Account
  description: The token owner, their workspaces and the workspace members.
paths:
  /v0/me:
    get:
      tags:
      - Account
      operationId: getMe
      summary: The token owner and their workspaces
      responses:
        '200':
          description: The token owner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Me'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v0/workspaces:
    get:
      tags:
      - Account
      operationId: listWorkspaces
      summary: Workspaces the token owner belongs to
      description: Not paginated; `next_cursor` is always null.
      responses:
        '200':
          description: The workspaces, by name.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v0/workspaces/{workspace_id}/members:
    get:
      tags:
      - Account
      operationId: listWorkspaceMembers
      summary: Members of a workspace, with their roles
      description: In the order they joined. Any member of the workspace can read it.
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of members.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Member'
                  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'
components:
  schemas:
    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
    Workspace:
      type: object
      required:
      - id
      - name
      - role
      - plan
      properties:
        id:
          type: string
        name:
          type: string
        role:
          $ref: '#/components/schemas/Role'
        plan:
          type: string
          enum:
          - free
          - trial
          - pro
    Role:
      type: string
      enum:
      - owner
      - admin
      - member
      - observer
    Me:
      type: object
      required:
      - id
      - name
      - workspaces
      properties:
        id:
          type: string
        name:
          type: string
        workspaces:
          type: array
          items:
            type: object
            required:
            - id
            - name
            - role
            properties:
              id:
                type: string
              name:
                type: string
              role:
                $ref: '#/components/schemas/Role'
    Member:
      type: object
      required:
      - id
      - name
      - role
      properties:
        id:
          type: string
          description: The user's id (use it as `user_id` and in `assignee_ids`).
        name:
          type: string
        role:
          $ref: '#/components/schemas/Role'
  responses:
    NotFound:
      description: The resource does not exist or the token owner cannot access it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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
    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'
    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'
    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'
  parameters:
    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
    WorkspaceId:
      name: workspace_id
      in: path
      required: true
      schema:
        type: string
  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.