AgileHero Cards API

openapi: 3.2.0
info:
  title: AgileHero Cards 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:


# --- truncated at 32 KB (43 KB total) ---
# Full source: https://artifacts.apis.io/agilehero-io/openapi/agilehero-io-cards-api-openapi.yml