Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: AgileHero Webhooks 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: Webhooks
description: Outbound webhook endpoints (REST Hooks subscribe, unsubscribe, list and sample). Workspace owners and admins only.
paths:
/v0/webhook_endpoints:
get:
tags:
- Webhooks
operationId: listWebhookEndpoints
summary: A workspace's webhook endpoints
description: Every endpoint of the workspace (at most 20), never with its secret. Workspace owners and admins only (`403 forbidden` for other roles). Not paginated; `next_cursor` is always null.
parameters:
- $ref: '#/components/parameters/WorkspaceIdQuery'
responses:
'200':
description: The endpoints.
content:
application/json:
schema:
type: object
required:
- data
- next_cursor
properties:
data:
type: array
items:
$ref: '#/components/schemas/WebhookEndpoint'
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'
post:
tags:
- Webhooks
operationId: createWebhookEndpoint
summary: Subscribe an endpoint (REST Hooks subscribe)
description: Registers an https endpoint for the workspace's events. The response carries the signing `secret` — the only time it is returned. Workspace owners and admins only. The Free plan allows 2 endpoints per workspace, trial and Pro 20; at the cap the answer is `422 validation_failed` with `details.base = ["webhook_endpoint_limit_reached"]`.
security:
- oauth2:
- api:read
- api:write
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- workspace_id
- url
properties:
workspace_id:
type: string
url:
type: string
description: https URL on a public address, port 443 or 1024 and up, not on agilehero.io or its subdomains, without credentials (max 2048 characters).
example: https://hooks.zapier.com/hooks/standard/123/abc
description:
type: string
maxLength: 255
event_types:
type: array
description: Event types to receive (see `WebhookEvent.type`); omitted or empty = all.
items:
type: string
example:
- card.created
project_ids:
type: array
description: Project ids of the workspace; omitted or empty = all projects. Workspace-level events (`workspace.member_removed`) reach only endpoints without a project filter.
items:
type: string
responses:
'201':
description: The new endpoint, with its secret.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/WebhookEndpoint'
'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/webhook_endpoints/sample:
get:
tags:
- Webhooks
operationId: sampleWebhookEvent
summary: A sample event body (REST Hooks perform list)
description: 'A list holding one event body of `event_type`: the workspace''s most recent real event of that type, or a synthetic example with the same shape when there is none. Workspace owners and admins only.'
parameters:
- $ref: '#/components/parameters/WorkspaceIdQuery'
- name: event_type
in: query
required: true
schema:
type: string
example: card.created
responses:
'200':
description: One sample event.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/WebhookEvent'
'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/webhook_endpoints/{webhook_endpoint_id}:
delete:
tags:
- Webhooks
operationId: deleteWebhookEndpoint
summary: Unsubscribe an endpoint (REST Hooks unsubscribe)
description: Deletes the endpoint and its delivery log. Workspace owners and admins only.
security:
- oauth2:
- api:read
- api:write
parameters:
- name: webhook_endpoint_id
in: path
required: true
schema:
type: string
responses:
'200':
description: The deleted endpoint.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/WebhookEndpoint'
'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'
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
NullableReference:
type:
- object
- 'null'
description: A reference, or null (a card's list is null in the backlog; its epic when it has none).
required:
- id
- name
properties:
id:
type: string
name:
type: string
WebhookEndpoint:
type: object
required:
- id
- url
- description
- event_types
- project_ids
- status
- disabled_reason
- created_at
- updated_at
properties:
id:
type: string
url:
type: string
description:
type:
- string
- 'null'
event_types:
type: array
items:
type: string
description: Empty = every event type.
project_ids:
type: array
items:
type: string
description: Empty = every project.
status:
type: string
enum:
- active
- disabled
disabled_reason:
type:
- string
- 'null'
enum:
- admin
- failures
- gone
- null
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
secret:
type: string
description: The `whsec_...` signing secret — only in the response that created the endpoint.
example: whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
WebhookEvent:
type: object
description: The body of every webhook request. `data` holds the affected resource under its name (`card`, `comment`, `epic`, `list`, `label`, `checklist_item`, `user`, `project`), plus a related one where the type implies it (`card.label_added` adds `label`, `card.assigned` adds `user`). Rich-text bodies are never included (`description_present` flags them).
required:
- id
- type
- occurred_at
- origin
- workspace
- project
- actor
- data
properties:
id:
type: string
description: The event id — also the `webhook-id` header.
type:
type: string
enum:
- card.created
- card.updated
- card.moved
- card.deleted
- comment.created
- comment.updated
- comment.deleted
- epic.created
- epic.updated
- epic.deleted
- list.created
- list.updated
- list.deleted
- label.created
- label.updated
- label.deleted
- card.label_added
- card.label_removed
- card.assigned
- card.unassigned
- epic.assigned
- epic.unassigned
- checklist_item.created
- checklist_item.updated
- checklist_item.deleted
- project.member_added
- project.member_removed
- workspace.member_removed
occurred_at:
type: string
format: date-time
origin:
type: string
enum:
- web
- mcp
- slack
- github
- api
workspace:
type: object
required:
- id
properties:
id:
type: string
project:
$ref: '#/components/schemas/NullableReference'
actor:
$ref: '#/components/schemas/NullableReference'
data:
type: object
additionalProperties: true
example:
card:
id: k3j9x2ab
title: Ship webhooks
changes:
type: object
description: 'On `*.updated` and `card.moved` only: each changed field as `{ from, to }`, or `{ changed: true }` for a rich-text body.'
additionalProperties: true
example:
title:
from: Old title
to: Ship webhooks
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'
BadRequest:
description: The request body could not be parsed (`invalid_request`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The resource does not exist or the token owner cannot access it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
WorkspaceIdQuery:
name: workspace_id
in: query
required: true
description: The workspace (its id from `GET /v0/workspaces`).
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.