REST API reference

Base URL

https://api.agilehero.io, every path starts with /v0

Sign-in

OAuth 2.1 at https://mcp.agilehero.io, authorization code with PKCE

Scopes

api:read for every endpoint; add api:write to create, change, or delete. Request only what you need.

Permissions

Your workspace role applies. Observers cannot use the API: a workspace where you are an observer is not listed, and everything in it answers 404

Rate limits

600/min per token, 1,200/min per IP, 60/min without a token; 429 + Retry-After

Pagination

{ data, next_cursor }; pass next_cursor as cursor; 50 per page, max 200

Errors

One body, { "error": { "code", "message", "details"? } }: 400 invalid_request · 401 unauthorized · 403 insufficient_scope · 403 forbidden · 404 not_found · 422 validation_failed · 429 rate_limited

Webhooks

Signed per Standard Webhooks; workspace owners and admins manage the webhook endpoints

OpenAPI

agilehero.io/api/openapi.yaml (OpenAPI 3.0)

First request

1. Identify your client. Publish a Client ID Metadata Document: a JSON file at an HTTPS URL you control that names your client and its redirect URIs. That URL is your client_id; there is no registration form and no client secret. The MCP docs explain why AgileHero signs clients in this way.
2. Get a token. Run the authorization-code flow with PKCE (S256) against https://mcp.agilehero.io (endpoints in its metadata), sending resource=https://api.agilehero.io/v0 and scope=api:read api:write (or just api:read for a read-only script) on both the authorization and the token request.
3. Call the API.

   curl https://api.agilehero.io/v0/me \
     -H "Authorization: Bearer <access token>"

   {
     "id": "k3v9x2mq",
     "name": "Ada Lovelace",
     "workspaces": [
       { "id": "w7p4n8rt", "name": "Acme", "role": "owner" }
     ]
   }

You sign in once, in a browser. Access tokens last an hour; trade the refresh token for a new pair and keep the new refresh token each time. Each refresh token stays valid for 30 days, so a script that runs at least monthly keeps working until you revoke it under Settings → AI clients in the app.

Connecting an AI assistant instead? The MCP server reference covers setup for Claude, ChatGPT, VS Code and other clients, and every agent tool.