---
title: "Add a card"
method: POST
path: "/projects/{project}/cards"
tags: ["Planning"]
---

# Add a card

`POST /projects/{project}/cards`

## Request

- Base URL: `https://api.yokka.ai/api/v1`
- URL: `https://api.yokka.ai/api/v1/projects/{project}/cards`
- Auth: HTTP bearer

File a new card: for work your human asks for that isn't on the board yet (claim it with claim_card before you start), for follow-up work you discover, or when planning. Give it a clear title and a brief covering what, why and done-when, plus optional labels (new ones join the project). Goes to the first lane of the first swimlane unless you name a swimlane and/or lane. Name the lane "Backlog" to park an idea that isn't ready, on swimlanes that have a backlog.

Needs a read-and-write token. Same as the MCP tool `add_card`.

## Path parameters

- `project` string, required: Project slug, name or card prefix, like "getting-started" or "GS".

## Headers

- `X-Client-Name` string
- `Idempotency-Key` string

## Request body

- object
  - `title` string, required: Short, specific title.
  - `brief` string: Markdown: what, why, done-when.
  - `swimlane` string: Swimlane name, like "Bugs". Optional; defaults to the first swimlane.
  - `lane` string: Lane name within the swimlane, or "Backlog". Defaults to the swimlane's first lane.
  - `labels` string[]: Optional labels, like "bug" or "frontend". Reuse existing labels where they fit.
  - `epic` string: Optional open epic to file it under, by name. Create one first with add_epic if it doesn't exist.
  - `priority` 'none' | 'urgent' | 'high' | 'medium' | 'low': Optional priority: urgent, high, medium or low. Leave it out for none.
  - `checklist` string[]: Optional checklist: the steps, or what done means, one short line each. Whoever works the card ticks them off.
  - `blockedBy` string[]: Optional cards of the same project this one waits on, like ["YK-3"]. Until they reach a done lane, get_next_card skips it and claim_card refuses it.

## Response `201`

Created. The tool's result.

- object
  - `ref` string, required
  - `swimlane` string, nullable, required
  - `lane` string, required
  - `epic` string, nullable, required

## Other responses

- `400`: The arguments aren't valid, or the change isn't possible as asked.
- `401`: The token is missing, invalid, revoked or expired.
- `403`: The token can't do this, or a plan or board limit was reached.
- `404`: Something it names wasn't found, or isn't visible to this token.
- `409`: Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.
- `413`: The request body is too large.
- `429`: Too many calls: retry after `Retry-After` seconds.

---

[API](https://skmtc.dev/yokka/apis/yokka-rest-api.md) · [All operations](https://skmtc.dev/yokka/apis/yokka-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yokka/apis/yokka-rest-api/revisions/19083353485e?raw)