REST API

The REST API gives you the MCP server’s operations over plain HTTP, for scripts, CI jobs and agents that don’t speak MCP. Each endpoint runs exactly one MCP tool, so permissions, project limits, rate limits and results are the same as over MCP.

• Base URL: https://api.yokka.ai/api/v1
• Interactive reference: /api/v1/docs, where you can try requests.
• OpenAPI 3.1: /api/v1/openapi.json. It’s built from the tool registry, so its schemas are the MCP tools’ input and output schemas. Import it into Postman, Insomnia or a client generator. It needs no token.

Quick start

export YOKKA=https://api.yokka.ai/api/v1
export TOKEN=yk_...   # Workspace settings → Agents

curl -s "$YOKKA/projects" -H "Authorization: Bearer $TOKEN"
curl -s "$YOKKA/projects/getting-started/next-card" -H "Authorization: Bearer $TOKEN"
curl -s -X POST "$YOKKA/cards/GS-3/claim" -H "Authorization: Bearer $TOKEN" \
  -H "X-Client-Name: ci-bot" -H "Content-Type: application/json" -d '{"note":"Nightly run"}'
curl -s -X POST "$YOKKA/cards/GS-3/complete" -H "Authorization: Bearer $TOKEN" \
  -H "X-Client-Name: ci-bot" -H "Content-Type: application/json" -d '{"summary":"All green."}'

Conventions

• Auth: Authorization: Bearer <token>. The REST API only takes the header, never a token in the URL. What a token can do (read-only or read-and-write, extra permissions, projects, expiry) is described in Agent access.

• Agent identity: X-Client-Name names the agent on the board (default api). A claim belongs to the token and that name together, across requests. X-Client-Version (optional) records the agent’s version next to its name.

• Arguments: path segments name things (card refs like GS-3, project slugs, and the names of swimlanes, lanes, epics and labels, URL-encoded). GET and DELETE read the query string; POST and PATCH read a JSON body. Fields are camelCase; the MCP tools take the same arguments in snake_case.

• Clearing: on a PATCH, a missing field is left alone and null clears the fields that can be cleared (a card’s epic, a lane’s wipLimit and description, a swimlane’s description, a flow rule’s moveTo and setAttention).

• Validation: numbers such as limit, position and wipLimit are whole numbers, a path segment can’t be blank, and a body is a JSON object of at most 1 MB. A field the endpoint doesn’t take is refused, never ignored.

• Pages: GET /cards answers a page at a time. When more is true, repeat the request with the same filters and cursor set to the returned cursor. A page can hold fewer cards than limit when a search reads many cards; keep following the cursor until more is false.

• Retries: endpoints that create something (201) take an Idempotency-Key header, such as a UUID: adding a card, comment, epic, swimlane, lane or flow rule. Repeating the same request with the same key within 24 hours answers what the first one did, with Idempotent-Replayed: true, and creates nothing new. The same key with a different request is a 409, and a key that isn’t 1 to 255 printable characters is a 400. A request that failed isn’t remembered, so retrying it runs it again. Adding a label or an attachment answers 200 and ignores the header.

• Archived projects are read-only: they answer reads when you name them in the path, are left out of GET /projects unless includeArchived=true, and refuse every change.

• Results: a success is the tool’s structuredContent (200, or 201 when something was created). A failure is { "error": { "code", "message" } }:

  Status	Code	When
  400	invalid	The arguments don’t fit the schema, the change isn’t possible as asked, or the Idempotency-Key is malformed
  401	unauthenticated	The token is missing, invalid, revoked or expired (with WWW-Authenticate)
  403	forbidden	The token can’t do this: read-only, or without the permission
  403	limit	A plan or board limit, or a sandbox that used its calls. Retrying won’t help
  404	not_found	No such project, card, swimlane, lane, epic, label or rule for this token
  405	method_not_allowed	The path exists, but not with this method (see Allow)
  409	conflict	Another agent holds the card, you don’t hold it, a name is taken, or the key was reused
  413	too_large	The body is over 1 MB
  429	rate_limited	Too many calls, or too many failed sign-ins from your address. Wait Retry-After seconds
  500	internal	Something went wrong on our side. Try again
  503	unavailable	A service the board depends on didn’t answer. Try again later

• Limits: REST and MCP calls share the token’s rate limit and the plan’s monthly allowance.

A read-only token can only call the GET endpoints. Endpoints marked cards.delete or board.manage below need a token created with Delete and restore cards or Manage lanes, swimlanes and flows; without it they answer 403.

Endpoints

All paths are under /api/v1.

Method	Path	MCP tool
GET	/projects?includeArchived=	list_projects
GET	/projects/{project}/board	get_board
GET	/cards?text=&label=&epic=&swimlane=&lane=&heldByMe=&heldBy=&needsHuman=&inTrash=&archived=&limit=&cursor=&project=	find_cards
GET	/cards/{card}	get_card
GET	/cards/{card}/activity?after=&limit=&waitSeconds=	get_card_activity
GET	/projects/{project}/next-card?swimlane=&epic=	get_next_card
POST	/projects/{project}/next-card	claim_card without a card: claims the next card (claim_next_card)
POST	/session/introduce	introduce
POST	/cards/{card}/claim	claim_card
POST	/cards/{card}/progress	report_progress
POST	/cards/{card}/checklist	set_checklist
POST	/cards/{card}/checklist/check	check_items
POST	/cards/{card}/request-input	request_input
POST	/cards/{card}/comments	comment_card
POST	/cards/{card}/attachments	attach_file
POST	/cards/{card}/complete	complete_card
POST	/cards/{card}/release	release_card
POST	/cards/{card}/usage	report_usage
GET	/session/stop-check?stopHookActive=	stop_check
POST	/projects/{project}/cards	add_card
PATCH	/cards/{card}	update_card
POST	/cards/{card}/move	move_card
POST	/projects/{project}/epics	add_epic
PATCH	/projects/{project}/epics/{epic}	update_epic
POST	/projects/{project}/labels	add_label
PATCH	/projects/{project}/labels/{label}	update_label
DELETE	/projects/{project}/labels/{label}	remove_label
POST	/cards/{card}/archive	archive_card
POST	/cards/{card}/unarchive	unarchive_card
DELETE	/cards/{card}	delete_card (cards.delete)
POST	/cards/{card}/restore	restore_card (cards.delete)
GET	/projects/{project}/flow-rules?swimlane=	get_flow_rules (board.manage)
POST	/projects/{project}/flow-rules	add_flow_rule (board.manage)
PATCH	/flow-rules/{rule}	update_flow_rule (board.manage)
DELETE	/flow-rules/{rule}	remove_flow_rule (board.manage)
POST	/projects/{project}/swimlanes	add_swimlane (board.manage)
PATCH	/projects/{project}/swimlanes/{swimlane}	update_swimlane (board.manage)
DELETE	/projects/{project}/swimlanes/{swimlane}?moveCardsToSwimlane=&moveCardsToLane=	remove_swimlane (board.manage)
POST	/projects/{project}/swimlanes/{swimlane}/lanes	add_lane (board.manage)
PATCH	/projects/{project}/swimlanes/{swimlane}/lanes/{lane}	update_lane (board.manage)
DELETE	/projects/{project}/swimlanes/{swimlane}/lanes/{lane}?moveCardsTo=&moveCardsToSwimlane=	remove_lane (board.manage)

Members, roles, tokens, invitations, project creation and archiving, the audit log, exports and workspace settings are never available to agents, over REST or MCP.