Create a new task or goal with nested child tasks.
Requires a valid API token in the Authorization header:
Authorization: Bearer <your_api_token>Method: POST
Endpoint: /api/tasks
Content-Type: application/json
| Parameter | Type | Required | Description |
|---|---|---|---|
task.title |
string | Yes | Clear, specific task title |
task.description |
string | Strongly Recommended | Detailed description with WHY, WHAT, and WHERE |
task.type |
string | Strongly Recommended | Type: work (new features), defect (bug fixes) or goal (a goal with nested tasks). Exact lowercase values only; omitted defaults to work, and any other value returns 422 (see Task Type Values). Exception: when task.tasks is non-empty the request always creates a goal and this top-level value is ignored; each child's type is still validated and must be work or defect, because a goal cannot contain another goal |
task.priority |
string | No | Priority: low, medium, high, critical (default: medium) |
task.complexity |
string | Strongly Recommended | Complexity: small, medium, large (default: small) |
task.needs_review |
boolean | No | Whether task requires human review (default: false) |
task.labels |
array | No | Label names on this board to attach, e.g. ["Bug", "backend"], matched case-insensitively. Labels must already exist on the board; an unknown name returns 422 and nothing is created (see Labels). Each child under task.tasks may carry its own labels |
| Parameter | Type | Required | Description |
|---|---|---|---|
task.key_files |
array | CRITICAL | Files that will be modified - prevents conflicts (see format below) |
task.dependencies |
array | Strongly Recommended | Array of task identifiers that must complete first (e.g., ["W1", "W2"]), or use 0-based indices for tasks within the same goal (e.g., [0, 1] - see Dependency Handling below). Each identifier must name a task on this board (or a child of the same goal); otherwise the request is refused with 422 dependencies: ["lists tasks that are not on this board: W900"] and nothing is created |
A single create cannot attach a task to an existing goal. There is no
parent_goal parameter, and parent_id is read-only:
- A client-sent
parent_idis stripped before the task is created and logged as a mass-assignment attempt. It is forbidden because it would let a client link a task under any goal, including one on another board, and inherit that goal's assignee. - A
parent_goalkey is dropped like any other unrecognised key, with no log line.
Either way the request still returns 201 and the new task has
parent_id: null. The only ways to put work under a goal are nested tasks on
a goal create (see Goal Creation with Nested Tasks)
or POST /api/tasks/batch; both create the goal and its
children together. parent_id is set by the server during that goal creation and
a task cannot be reparented via the API — ask a human to change the parent goal
in the board UI.
| Parameter | Type | Required | Description |
|---|---|---|---|
task.why |
string | Strongly Recommended | Why this task matters - business justification |
task.what |
string | Strongly Recommended | What needs to be done - concise summary |
task.where_context |
string | Strongly Recommended | Where in the codebase this work happens |
task.estimated_files |
string | Strongly Recommended | Estimated number of files to modify as a number or range (e.g., '2', '3-5', '5+') |
| Parameter | Type | Required | Description |
|---|---|---|---|
task.acceptance_criteria |
string | Strongly Recommended | Specific, testable conditions for "done" (newline-separated) |
task.verification_steps |
array | Strongly Recommended | Array of step objects with step_type (command or manual), step_text and position, plus an optional expected_result (see Verification Steps Format) |
task.patterns_to_follow |
string | No | Specific coding patterns to replicate (newline-separated) |
task.database_changes |
string | No | Database schema changes required (migrations, tables, columns) |
task.validation_rules |
string | No | Input validation requirements (constraints, formats, rules) |
task.technology_requirements |
array | No | Required technologies or libraries (array of strings) |
task.pitfalls |
array | No | Common mistakes to avoid (array of strings) |
task.out_of_scope |
array | No | What NOT to include in this task (array of strings) |
| Parameter | Type | Required | Description |
|---|---|---|---|
task.telemetry_event |
string | No | Telemetry events to emit (event names and metadata). Stored only on a board in an Organization; see Warnings |
task.metrics_to_track |
string | No | Metrics to instrument (counters, gauges, histograms). Stored only on a board in an Organization; see Warnings |
task.logging_requirements |
string | No | What to log for debugging (log levels, context data) |
task.error_user_message |
string | No | User-facing error messages to display |
task.error_on_failure |
string | No | How to handle failures (retry logic, fallbacks, cleanup) |
| Parameter | Type | Required | Description |
|---|---|---|---|
task.security_considerations |
array | Strongly Recommended | Security concerns, vulnerabilities to avoid, or security requirements (array of strings - see format below). An entry shaped like a real credential is rejected with a 422 |
task.testing_strategy |
object | Strongly Recommended | Overall testing approach (JSON object - see format below) |
task.integration_points |
object | No | Systems or APIs this touches (JSON object) |
| Parameter | Type | Required | Description |
|---|---|---|---|
task.required_capabilities |
array | No | Required agent capabilities (e.g., ["code_generation", "testing"]) |
task.column_id |
integer | No | Column ID where task should be created. Omitted, the task goes to the board's column named Backlog; a board with no Backlog uses its Ready column, and a board with neither uses its first column. Sent as a JSON number or a numeric string. A value that is not an integer returns 400 Invalid column_id: must be an integer. A column that does not exist or is on another board returns 404 Column not found (Task not found before 2026-10-21), and so does a whole number outside the signed 64-bit range. Omitted on a board with no columns at all, it also returns 404 Column not found and nothing is created. |
task.tasks |
array | No | Array of child task objects (for goals only). Each child's type must be work or defect; a child of type goal returns 422, and so does a child with a non-empty tasks list of its own (see Unprocessable Entity (422)) |
agent_name |
string | No | Top-level (sibling of task, not nested inside it): the display name of the agent creating the task, used for created_by_agent attribution (see resolution order below) |
The server records who created each task in the create-only created_by_agent
field (it is rejected on PATCH so attribution history stays immutable). At
create time the value is resolved from the first available source:
- An explicit
task.created_by_agentin the payload (always wins) - The API token's
agent_model, recorded asai_agent:<model> - The request's top-level
agent_nameparameter, when it is a usable name - The token's remembered
last_agent_name— stamped automatically whenever a claim, complete, create, or comment request carries a usableagent_name. A usable name is valid UTF-8, contains no NUL, has at least one visible character (whitespace and invisible format characters such as zero-width or bidi controls do not count), and is not the"Unknown"placeholder - Otherwise the task is created unattributed (
created_by_agentisnull) and the agents page renders its created row with the neutral?avatar
The key_files array should contain objects with the following structure:
"key_files": [
{
"file_path": "lib/path/to/file.ex", // Required: relative path from project root
"note": "Why this file is modified", // Optional: context
"position": 0 // Required: order of modification (0-indexed)
}
]Why key_files is CRITICAL:
- Prevents merge conflicts - only one task can modify a file at a time
GET /api/tasks/nextand a claim without anidentifierskip a Ready task whose key_files overlap a task in progress in Doing or Review- If Task A is working on
lib/auth.ex, Task B listing the same file is not offered until Task A completes. A claim that names Task B withidentifierdoes not run this check
The verification_steps array MUST contain objects with the following structure:
"verification_steps": [
{
"step_type": "command", // Required: "command" or "manual"
"step_text": "mix test test/auth_test.exs", // Required: command or instruction
"expected_result": "All tests pass", // Optional: what success looks like
"position": 0 // Required: execution order (0-indexed)
},
{
"step_type": "manual",
"step_text": "Navigate to /login and verify special characters work in password field",
"expected_result": "Can login with password containing &, %, #",
"position": 1
}
]verification_steps array MUST be an object (not a string, not an empty array).
Valid:
"verification_steps": [{"step_type": "command", "step_text": "mix test", "position": 0}]"verification_steps": [](empty array is valid but not useful)
Invalid (will cause error):
"verification_steps": ["mix test"](array of strings)"verification_steps": "mix test"(string instead of array)
The testing_strategy object describes the overall testing approach for the task. This is a flexible JSON object that can contain any relevant testing information. Common fields include:
"testing_strategy": {
"unit_tests": "Test each function in isolation with ExUnit",
"integration_tests": "Test auth flow end-to-end in controller tests",
"property_tests": "Use StreamData to verify password encoding with random special characters",
"coverage_target": "100% for auth module",
"test_data": "Create fixtures for valid/invalid passwords",
"mocking": "Mock external email service for password reset tests",
"edge_cases": [
"Empty password",
"Password with unicode characters",
"Password exceeding max length"
],
"performance_tests": "Login should complete in <100ms for 95th percentile"
}Common fields (all optional):
unit_tests(string) - Approach for unit testing individual functionsintegration_tests(string) - How to test component interactionsproperty_tests(string) - Property-based testing strategy (e.g., StreamData)coverage_target(string) - Target code coverage percentage or scopetest_data(string) - Test fixtures or data setup approachmocking(string) - What external dependencies to mock and howedge_cases(array) - Specific edge cases that must be testedperformance_tests(string) - Performance criteria or benchmarksmanual_tests(string) - Manual testing procedures beyond automated tests
Why testing_strategy is valuable:
- Provides clear testing expectations beyond verification steps
- Helps agents understand the testing philosophy for this task
- Specifies coverage targets and edge cases upfront
- Documents mocking/stubbing requirements
- Can be more comprehensive than
verification_stepswhich focuses on commands
When to use testing_strategy vs verification_steps:
testing_strategy- Overall testing approach, coverage goals, edge cases to considerverification_steps- Specific commands to run and manual steps to verify completion
Use both for comprehensive guidance: testing_strategy tells the agent how to think about testing, while verification_steps tells them what commands to run.
The security_considerations array specifies security concerns, potential vulnerabilities, and security requirements for the task. This is an array of strings, each describing a specific security aspect to address.
"security_considerations": [
"Validate and sanitize all user input to prevent XSS attacks",
"Use parameterized queries to prevent SQL injection",
"Hash passwords with bcrypt (cost factor 12+)",
"Implement rate limiting on login endpoint (max 5 attempts per minute)",
"Ensure authentication tokens expire after 24 hours",
"Never log sensitive data (passwords, tokens, credit cards)",
"Use HTTPS only for all authentication endpoints",
"Implement CSRF protection for state-changing operations"
]Common security considerations by category:
Input Validation & Sanitization:
- "Validate and sanitize user input to prevent XSS"
- "Escape HTML in user-generated content"
- "Validate file uploads (type, size, content)"
- "Reject invalid email formats and special characters"
Authentication & Authorization:
- "Hash passwords with bcrypt (cost factor 12+)"
- "Implement secure password reset flow with time-limited tokens"
- "Verify user authorization before allowing access"
- "Use secure session management"
- "Implement multi-factor authentication"
Data Protection:
- "Never log passwords, tokens, or sensitive data"
- "Encrypt sensitive data at rest"
- "Use HTTPS/TLS for all data transmission"
- "Implement proper access controls on sensitive resources"
Injection Prevention:
- "Use parameterized queries to prevent SQL injection"
- "Validate and sanitize all database inputs"
- "Prevent command injection in system calls"
- "Escape user input in dynamic queries"
Rate Limiting & DoS Prevention:
- "Implement rate limiting (5 requests per minute per IP)"
- "Add CAPTCHA after failed login attempts"
- "Limit file upload sizes"
- "Implement request throttling"
CSRF & Session Security:
- "Implement CSRF token validation"
- "Set secure cookie flags (HttpOnly, Secure, SameSite)"
- "Invalidate sessions on logout"
- "Rotate session tokens after privilege changes"
Credential-shaped entries are rejected. Security-review agents echo each
consideration verbatim into the review result Stride stores and shows on the
Review queue, so an entry must never carry a real secret. An entry that matches
a concrete credential format is refused with a
422 and nothing is stored. The formats are a Stride
API token, Bearer followed by a token, a PEM or PGP private key header, a
JWT, a user:password@ segment in a URL, GitHub, OpenAI-style, AWS and Slack
keys, and a password=/secret=/api_key=-style assignment of a long opaque
value. Describe the risk in words instead.
Prose about credentials is accepted, because the check matches token formats
rather than words: "API tokens are never logged" and the redaction sentinel
[REDACTED — row text embedded a credential] both pass, and so does a short
placeholder such as stride_dev_abc123. Two non-secret shapes are refused
anyway, because loosening the patterns to admit them would also admit real
tokens: bearer followed by one unbroken word of 20 or more characters, and an
auth_token:-style label followed by a long unbroken value such as a file
path. Reword either one.
Why security_considerations is valuable:
- Prevents vulnerabilities - Explicitly reminds agents of security risks
- OWASP awareness - Addresses common security issues (SQL injection, XSS, CSRF, etc.)
- Compliance - Ensures security best practices are followed
- Code review - Provides security checklist for reviewers
- Reduces risk - Makes security a first-class concern, not an afterthought
When to include security_considerations:
- Always for tasks involving:
- User authentication or authorization
- User input or file uploads
- Database operations with user data
- API endpoints accepting external data
- Payment or financial transactions
- Personal or sensitive data handling
- Session or token management
task.labels attaches existing board labels to the new task by name:
{
"task": {
"title": "Fix login redirect loop",
"type": "defect",
"labels": ["Bug", "auth"]
}
}- Names are matched case-insensitively against the labels of the token's
board, with surrounding whitespace ignored. Duplicates, including case
variants such as
"bug"and"BUG", attach the label once. - Each name must be a string of 1 to 40 characters, and
labelsmust be an array. Send[](or omit the field) for no labels;nullis rejected. - Labels are never created by the API. Create, rename and delete labels in the board settings; the API only attaches labels that already exist.
- Every name is checked before anything is written. If any name is not a label on this board, the request returns 422 naming every unknown name and no task is created — for a goal, neither the goal nor any child. A name that exists only on another board is reported in exactly the same words as one that exists nowhere.
- A goal's own
labelsapply to the goal; each child task intask.taskscan carry its ownlabels, which are checked the same way. - The response's
data.labelslists the attached labels as{name, color}, ordered by name ignoring case. Goal-creation responses keep their compact shapes; fetch a task with GET /api/tasks/:id to read its labels.
{
"task": {
"title": "Fix login bug with special characters in password",
"type": "defect",
"description": "Users cannot log in when their password contains special characters like & or %.",
"why": "Users cannot authenticate when using strong passwords with special characters, blocking access to their accounts",
"what": "Fix password encoding in login form to properly handle special characters",
"where_context": "Authentication controller and login form validation",
"priority": "high",
"complexity": "small",
"estimated_files": "2",
"needs_review": true,
"key_files": [
{
"file_path": "lib/kanban_web/controllers/auth_controller.ex",
"note": "Fix password encoding before validation",
"position": 0
},
{
"file_path": "test/kanban_web/controllers/auth_controller_test.exs",
"note": "Add test for special characters",
"position": 1
}
],
"acceptance_criteria": "Users can log in with passwords containing &, %, #, and @ characters\nPassword validation works correctly with special chars\nNo regression in normal password login",
"verification_steps": [
{
"step_type": "command",
"step_text": "mix test test/kanban_web/controllers/auth_controller_test.exs",
"expected_result": "All tests pass",
"position": 0
},
{
"step_type": "manual",
"step_text": "Create user with password 'Test&Pass%123' and login",
"expected_result": "Login succeeds with special characters in password",
"position": 1
}
],
"database_changes": null,
"validation_rules": "Password must be URL-encoded before transmission to server",
"testing_strategy": {
"unit_tests": "Test password encoding function with various special characters",
"integration_tests": "Test full login flow with passwords containing &, %, #, @",
"edge_cases": [
"Password with only special characters",
"Password with unicode characters",
"Empty password",
"Very long password with special chars"
],
"coverage_target": "100% for modified auth functions"
},
"required_capabilities": ["code_generation", "testing"]
}
}{
"task": {
"title": "Fix login bug",
"description": "Users can't log in with special characters in password",
"priority": "high",
"complexity": "small"
}
}Note: While the minimal example above is valid, it lacks critical information that would help an agent (or developer) implement it efficiently. Always prefer the detailed approach.
{
"task": {
"title": "Implement user authentication system",
"description": "Complete authentication system with JWT tokens, password hashing, and session management.",
"why": "Application needs secure user authentication to protect user data and restrict access",
"what": "Complete authentication system with JWT tokens, password hashing, and session management",
"where_context": "New auth module and controllers",
"type": "goal",
"priority": "critical",
"complexity": "large",
"estimated_files": "10+",
"tasks": [
{
"title": "Create database schema for users",
"type": "work",
"description": "Add users table with email, password_hash, and metadata fields.",
"why": "Need secure storage for user credentials and authentication data",
"what": "Add users table with email, password_hash, and metadata fields",
"where_context": "New migration and User schema module",
"priority": "critical",
"complexity": "medium",
"estimated_files": "2",
"key_files": [
{
"file_path": "priv/repo/migrations/*_create_users.exs",
"note": "Create users table migration",
"position": 0
},
{
"file_path": "lib/kanban/accounts/user.ex",
"note": "User schema with validations",
"position": 1
}
],
"acceptance_criteria": "Migration creates users table with email, password_hash, inserted_at, updated_at\nEmail has unique constraint\nSchema validates email format and password length",
"verification_steps": [
{
"step_type": "command",
"step_text": "mix ecto.migrate",
"expected_result": "Migration runs successfully",
"position": 0
},
{
"step_type": "command",
"step_text": "mix test test/kanban/accounts/user_test.exs",
"expected_result": "All tests pass",
"position": 1
}
],
"required_capabilities": ["code_generation"]
},
{
"title": "Implement JWT token generation and validation",
"type": "work",
"description": "Add JWT library, create token generation and validation functions.",
"why": "Need secure token-based authentication for stateless API access",
"what": "Add JWT library, create token generation and validation functions",
"where_context": "Auth context module",
"priority": "critical",
"complexity": "medium",
"estimated_files": "2-3",
"dependencies": [0],
"key_files": [
{
"file_path": "lib/kanban/accounts/auth.ex",
"note": "Token generation and validation logic",
"position": 0
},
{
"file_path": "mix.exs",
"note": "Add joken dependency",
"position": 1
}
],
"acceptance_criteria": "generate_token/1 creates valid JWT with user_id claim\nverify_token/1 validates token signature and expiry\nTokens expire after 24 hours\nInvalid tokens return error tuple",
"verification_steps": [
{
"step_type": "command",
"step_text": "mix test test/kanban/accounts/auth_test.exs",
"expected_result": "All tests pass",
"position": 0
}
],
"technology_requirements": ["Joken library"],
"database_changes": null,
"validation_rules": "Tokens must use HS256 algorithm and expire after 24 hours",
"security_considerations": [
"Store JWT secret in environment variable, never in code",
"Use HS256 algorithm for token signing",
"Ensure tokens expire after 24 hours"
],
"testing_strategy": {
"unit_tests": "Test token generation and validation functions independently",
"integration_tests": "Not needed - covered by auth controller tests",
"edge_cases": [
"Expired token",
"Invalid signature",
"Missing user_id claim",
"Malformed token string"
],
"coverage_target": "100% for token module"
},
"required_capabilities": ["code_generation"]
},
{
"title": "Write comprehensive authentication tests",
"type": "work",
"description": "Test suite covering all auth flows and edge cases.",
"why": "Ensure auth system is secure and reliable before deploying to production",
"what": "Test suite covering all auth flows and edge cases",
"where_context": "Test files for auth modules",
"priority": "high",
"complexity": "medium",
"estimated_files": "3-4",
"dependencies": [1],
"key_files": [
{
"file_path": "test/kanban/accounts/auth_test.exs",
"note": "Auth context tests",
"position": 0
},
{
"file_path": "test/kanban/accounts/user_test.exs",
"note": "User schema tests",
"position": 1
}
],
"acceptance_criteria": "100% code coverage for auth module\nAll happy path scenarios tested\nAll error cases tested\nTests run in < 1 second",
"verification_steps": [
{
"step_type": "command",
"step_text": "mix test test/kanban/accounts/",
"expected_result": "All tests pass",
"position": 0
},
{
"step_type": "command",
"step_text": "mix test --cover --export-coverage default",
"expected_result": "Coverage report generated",
"position": 1
},
{
"step_type": "command",
"step_text": "mix test.coverage",
"expected_result": "100% coverage for auth module",
"position": 2
}
],
"required_capabilities": ["testing"]
}
]
}
}{
"data": {
"id": 124,
"identifier": "W22",
"title": "Fix login bug",
"description": "Users can't log in with special characters in password",
"status": "open",
"priority": "high",
"complexity": "small",
"needs_review": true,
"type": "work",
"column_id": 5,
"created_by_id": 5,
"created_by_agent": "ai_agent:claude-sonnet-4-5",
"required_capabilities": ["code_generation"],
"labels": [
{"name": "Bug", "color": "red"}
],
"inserted_at": "2025-12-28T13:00:00Z",
"updated_at": "2025-12-28T13:00:00Z"
},
"current_skills_version": "1.0"
}{
"goal": {
"id": 125,
"identifier": "G10",
"title": "Implement user authentication system",
"description": "Complete authentication system with JWT tokens",
"status": "open",
"priority": "critical",
"complexity": "large",
"type": "goal",
"column_id": 5,
"created_by_agent": "ai_agent:claude-sonnet-4-5",
"inserted_at": "2025-12-28T13:00:00Z"
},
"child_tasks": [
{
"id": 126,
"identifier": "W23",
"title": "Create database schema for users",
"status": "open",
"priority": "critical",
"complexity": "medium",
"column_id": 5,
"dependencies": []
},
{
"id": 127,
"identifier": "W24",
"title": "Implement JWT token generation",
"status": "blocked",
"priority": "critical",
"complexity": "medium",
"column_id": 5,
"dependencies": ["W23"]
},
{
"id": 128,
"identifier": "W25",
"title": "Write authentication tests",
"status": "blocked",
"priority": "high",
"complexity": "medium",
"column_id": 5,
"dependencies": ["W24"]
}
]
}Each child_tasks entry is the compact task summary plus column_id, the
column the child was placed in. A goal's children are always placed in the
goal's column, so it equals the goal's column_id.
telemetry_event and metrics_to_track are paid fields. When paid plans are
enforced and the token's board is not in an Organization's workspace, the
request still succeeds with its normal status, but those fields are not
stored, on the task or on any child task. The response then carries a
top-level warnings list with one message naming the fields that were
dropped. The message never repeats the values you sent. A request that sends
neither field gets no warnings key. For a goal, warnings sits beside
goal and child_tasks.
{
"data": { "id": 123, "identifier": "W22", "title": "Add metrics dashboard" },
"warnings": [
"telemetry_event, metrics_to_track need a board in an Organization and were not stored."
],
"current_skills_version": "1.0"
}The token is missing or invalid. See 401 for a missing or invalid token.
The token's user does not have owner or modify access to the board. This is checked before anything is created:
{
"error": "Not authorized — board write access (owner or modify) required",
"documentation": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/api/README.md",
"getting_started": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/GETTING-STARTED-WITH-AI.md"
}task.column_id names a column that does not exist or belongs to another
board, or it is omitted on a board with no columns at all (D452). The cases are
deliberately indistinguishable, and nothing is created:
{
"error": "Column not found"
}Before 2026-10-21 this body read Task not found.
A task.column_id that is a whole number outside the signed 64-bit range (below
-9223372036854775808 or above 9223372036854775807) gets this same 404, whether
it is sent as a JSON number or as a string. It is never a 500. A column_id
that is not an integer at all, such as "abc", gets a 400 with
Invalid column_id: must be an integer instead. See
404 for out-of-range numeric IDs.
Validation errors:
{
"errors": {
"title": ["can't be blank"],
"priority": ["is invalid"]
}
}Unrecognised task type (for example "bug", "task", "Work" or 42). The
value you sent is not echoed back, and nothing is persisted:
{
"errors": {
"type": ["is invalid"]
},
"documentation": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/TASK-WRITING-GUIDE.md#task-types"
}An explicit "type": null, or an empty or whitespace-only string, returns
"type": ["can't be blank"] instead. When the
invalid type is on a nested child task, the same 422 is returned and neither the
goal nor any child is created.
A nested child task of type goal. Stride has two levels: a goal contains work
and defect tasks and never another goal, so the request is refused before any
identifier is assigned and neither the goal nor any child is created:
{
"errors": {
"type": ["must be 'work' or 'defect' for a task inside a goal; a goal cannot contain another goal"]
},
"documentation": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/TASK-WRITING-GUIDE.md#task-types"
}A nested child task with a non-empty tasks list of its own. Tasks nest one
level only, so the request is refused the same way instead of silently dropping
the inner list, and nothing is created. An empty tasks list on a child is
accepted:
{
"errors": {
"tasks": ["must be empty for a task inside a goal; tasks cannot be nested more than one level"]
}
}The response also carries the usual documentation link.
A security_considerations entry shaped like a real credential (see
Security Considerations Format). The error
names the entry by its 1-based position and never echoes the value, and nothing
is stored. When the entry is on a nested child task, the same 422 is returned
and neither the goal nor any child is created:
{
"errors": {
"security_considerations": ["entry 2 looks like it contains a credential; remove the secret value and describe the risk in words"]
}
}The response also carries the usual documentation link.
An unknown label name (see Labels). Every unknown name is listed,
including one that exists only on another board, and nothing is created. An
unknown name on a nested child is prefixed with that child's 0-based index in
task.tasks:
{
"errors": {
"labels": [
"unknown labels: \"Nope\"",
"tasks[1] unknown labels: \"Secret\""
]
}
}A labels value that is not an array of 1 to 40 character names (for example
"Bug", [1], [""] or null) returns "labels": ["must be an array of label names, each 1 to 40 characters"] the same way. Both responses also
carry the usual documentation link.
WIP limit reached. A work or defect task whose target column (Backlog by
default) already holds as many non-archived work and defect tasks as the
column's WIP limit allows is rejected, and nothing is persisted. The message is
fixed: it never echoes your title, type or column. A WIP limit of 0 means
unlimited, so such a column never returns this error:
{
"error": "WIP limit reached for this column — work and defect tasks cannot be added until a slot frees up",
"documentation": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/api/post_tasks.md#unprocessable-entity-422",
"common_causes": [
"The target column (Backlog by default) already holds as many work and defect tasks as its WIP limit allows",
"WIP limits count only non-archived work and defect tasks; goals are never counted or blocked",
"Wait for a task to leave the column, archive one, or ask a board owner to raise the column's WIP limit (0 means unlimited)"
]
}WIP limits apply only to work and defect tasks created on their own. A
goal is never counted or blocked, and creating a goal with nested child tasks
does not check the limit either: the goal is exempt and its children are not
checked against the limit when they are created, so a goal-with-tasks request
into a full column still returns 201 and can take the column past its limit.
Once created, those children count toward the limit like any other work or
defect task, so a later single create into that column can get this 422.
The check runs after board write access and the column lookup, so a 403 or 404
is returned before any WIP rejection. To act on this error, wait for a task to
leave the column or ask a board owner to raise the limit; retrying immediately
returns the same 422.
- A task sent without
task.column_idis created in the board's Backlog column, or in Ready when the board has no Backlog, or else in the board's first column - The
created_by_idis automatically set to your user ID - If your API token has an
agent_model, it's recorded ascreated_by_agent - Task identifiers are automatically generated (e.g., W22, G10)
labelsattaches existing board labels by name; it never creates a label (see Labels)
- Set
type: "goal"to create a goal - Include a
tasksarray to create child tasks atomically - When
tasksis non-empty the request always creates a goal: the top-leveltypeis ignored, but every child'stypeis validated (see Task Type Values) - Each child must be
workordefect. Goals are never nested: a child of typegoalreturns 422 and nothing is created - Tasks nest one level only: a child with a non-empty
taskslist of its own returns 422 and nothing is created - All tasks are created in a single database transaction (all-or-nothing)
- Column WIP limits are not checked when a goal and its children are created, so a full target column does not reject a goal-with-tasks request; once created, the children count toward the column's limit like any other task
- Child tasks are automatically linked to the parent goal: the server sets each
child's
parent_idto the new goal's id. Nested creation here, or the same nesting inPOST /api/tasks/batch, is the only way a task gets a parent through the API (see the note under Task Scheduling & Dependencies) - Child tasks are always created in the goal's column, on the goal's board. A
column_idon a child task is ignored, so a child can never be placed in another column or on another board - Child tasks can have dependencies on each other using index-based references
- The goal gets a
Gidentifier, work children getWidentifiers and defect children getDidentifiers; each identifier is unique on the board
When creating a goal with child tasks, you cannot use task identifiers like "W1" in dependencies because those identifiers haven't been assigned yet. Instead, use 0-based array indices:
How it works:
- Use 0-based array indices to reference tasks within the same goal
- Index 0 = first task, index 1 = second task, etc.
- The system automatically converts indices to actual task identifiers during creation
- Result stored in database has human-readable identifiers
- A string identifier must name a task already on the board or one of the goal's own children; an identifier with no task there refuses the whole goal with 422
Example:
{
"task": {
"title": "User Authentication",
"type": "goal",
"tasks": [
{"title": "Create schema", "type": "work"}, // index 0
{"title": "Add endpoints", "type": "work", "dependencies": [0]}, // depends on index 0
{"title": "Add tests", "type": "work", "dependencies": [0, 1]} // depends on indices 0 and 1
]
}
}After creation, stored in database as:
{
"goal": {"identifier": "G1", "title": "User Authentication"},
"child_tasks": [
{"identifier": "W47", "title": "Create schema", "dependencies": []},
{"identifier": "W48", "title": "Add endpoints", "dependencies": ["W47"]},
{"identifier": "W49", "title": "Add tests", "dependencies": ["W47", "W48"]}
]
}You can also mix indices with existing task identifiers:
{
"task": {
"title": "Feature Extension",
"type": "goal",
"tasks": [
{"title": "New component", "type": "work"},
{"title": "Integration", "type": "work", "dependencies": [0, "W23"]} // index 0 + existing task W23
]
}
}For standalone tasks (not in a goal):
Use existing task identifiers directly:
{
"task": {
"title": "Standalone task",
"type": "work",
"dependencies": ["W23", "W24"] // Use actual identifiers for existing tasks
}
}- Required capabilities filter which agents can claim the task
- Valid capabilities are the 16 values in Standard Capabilities, for example
code_generation,code_review,devops,documentationandtesting. Any other value, such asreviewordeployment, is rejected with a 422 and nothing is created - If not specified, any agent can claim the task
- Agents specify their capabilities in their API token configuration
work- New functionality or an enhancement (default whentypeis omitted)defect- A bug fixgoal- A goal; nest its child tasks undertasks. A goal is always top-level: it can never be the child of another goal, sogoalis not a valid type for a nested child task
The match is exact: values are lowercase with no surrounding whitespace, so
Work, WORK and " work" are rejected, as are mistaken names such as bug,
task or epic, null, an empty or whitespace-only string, numbers, arrays
and objects. A rejected type returns the 422 shown under
Unprocessable Entity (422) and creates nothing. To
get the work default, omit the type key entirely.
WIP limits apply only to work and defect, and only when one is created on
its own; a goal and the children nested under it are never checked. A request
with an invalid type is never counted against a WIP limit; it is rejected for
its type. See Unprocessable Entity (422) for the
WIP response body.
low- Nice to havemedium- Normal priority (default)high- Importantcritical- Urgent, must be done ASAP
small- Less than 1 hour (default)medium- 1-2 hourslarge- More than 2 hours
curl -X POST \
-H "Authorization: Bearer stride_dev_abc123..." \
-H "Content-Type: application/json" \
-d '{
"task": {
"title": "Fix login bug",
"description": "Users cannot log in with special characters",
"priority": "high",
"complexity": "small"
}
}' \
https://www.stridelikeaboss.com/api/taskscurl -X POST \
-H "Authorization: Bearer stride_dev_abc123..." \
-H "Content-Type: application/json" \
-d '{
"task": {
"title": "Implement authentication",
"type": "goal",
"priority": "critical",
"tasks": [
{"title": "Create user schema", "complexity": "medium"},
{"title": "Implement JWT tokens", "complexity": "medium"},
{"title": "Write tests", "complexity": "medium"}
]
}
}' \
https://www.stridelikeaboss.com/api/tasks- GET /api/tasks - List tasks (filters, cursor pagination)
- GET /api/tasks/:id - Get task details
- POST /api/tasks/claim - Claim a task to start working