Skip to content

Change a mission

PATCH
/v1/missions/{id}
curl --request PATCH \
--url https://beta-api.plune.ai/v1/missions/example \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "state": "active" }'

Any of name, summary, address, state and the answer about documentation; at least one. url: null takes the address off. No route deletes a mission: done ends one. The tier caps the missions active at once across all projects of the account (Free 1; Personal, Team and Enterprise none) - the projects of a company count on the company, apart from the account’s own, and a project in the Bin does not count. A write that would make one more active (started active, draft → active, or done → active) is refused with 429 and quota.kind: "activeMissions" - for example { "error": "Free plan limit reached — at most 1 active mission per account, across all its projects. Finish another active mission (mark it done), or move to the Personal plan, which has no such limit. / …", "quota": { "kind": "activeMissions", "limit": 1, "used": 1, "remaining": 0, "resetsAt": null } }. It is a quota, not a throttle: no Retry-After, a retry frees nothing - marking another mission done does. It only refuses once the operator sets TIER_LIMITS_ENFORCE=true; until then it is counted and logged.

id
required
string

The mission’s id

Media type application/json
object
>= 1 properties
name

The mission’s name

string
>= 1 characters <= 200 characters
summary
string
<= 2000 characters
url

Where the product is reached; null takes it off; http or https only

string format: uri
nullable <= 2048 characters
state
string
Allowed values: draft active done
documentation
string
Allowed values: unknown provided none
Example
{
"state": "active"
}

The mission as it is now

Media type application/json
object
id
required
string
projectId
required
string
name
required
string
summary
required

What the product is, in a few sentences; empty until written

string
url
required

Where the product is reached

string
nullable
state
required
string
Allowed values: draft active done
documentation
required

Is there documentation? unknown until somebody answers; provided — it is among the sources; none — the product has none

string
Allowed values: unknown provided none
createdBy
required
string
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
sources
required

Oldest first

Array<object>
object
id
required
string
kind
required

A link of four kinds, or mcp: an MCP server, added by POST /v1/missions/{id}/sources; or file, uploaded by POST /v1/missions/{id}/files

string
Allowed values: file url openapi repo ticket mcp
ref
required

The link; a file source’s file name; an mcp source’s address (http) or command line (stdio)

string
title
required
string
nullable
version
required

The source’s version as its owner names it: a commit, a tag, a document’s revision, an ETag

string
nullable
addedBy
required

The user who added it: the person, or the person whose token the agent used

string
createdAt
required
string format: date-time
bytes

A file source only: its size in UTF-8 bytes

integer
mediaType

A file source only: its type, read off its name

string
Allowed values: text/plain text/markdown application/json
mcp

An mcp source only (#2463): how the server is reached, and the NAMES of the environment variables that hold its secrets - never a value. tokenEnv (http): the variable whose value goes in the Authorization header; env (stdio): the variables the command is started with.

object
transport
required
string
Allowed values: http stdio
tokenEnv

http only

string
<= 128 characters /^[A-Za-z_][A-Za-z0-9_]*$/
env

stdio only

Array<string>
<= 50 items
Example
{
"id": "6f1c2b3a-0000-4000-8000-000000002188",
"projectId": "u-shop::default",
"name": "Shop checkout",
"summary": "An online shop. A customer fills a cart, pays by card or with a voucher, and gets a receipt by email.",
"url": "https://shop.example.com",
"state": "active",
"documentation": "provided",
"createdBy": "6f1c2b3a-0000-4000-8000-0000000000a2",
"createdAt": "2026-11-04T09:00:00.000Z",
"updatedAt": "2026-11-04T09:05:00.000Z",
"sources": [
{
"id": "6f1c2b3a-0000-4000-8000-000000002189",
"kind": "openapi",
"ref": "https://shop.example.com/openapi.json",
"title": "Shop API",
"version": "2026-11-01",
"addedBy": "6f1c2b3a-0000-4000-8000-0000000000a2",
"createdAt": "2026-11-04T09:05:00.000Z"
}
]
}

Invalid JSON or body, or nothing to change

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No / invalid token or session

You are in the project as a reader, or the token is read-only

No such mission in your project

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

Two refusals share this status, and what to do about them is opposite. Rate-limited — the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442, #2092): Retry-After carries the seconds until the window rolls over, and waiting that long is the way out. Quota reached — a ceiling on what the project holds (runs in the last 24 hours, test cases, items waiting in the review queue, rules in force in the project’s memory): { error, quota }. A retry straight away frees nothing, so do not loop on it; the message says what makes room — deleting cases, working the queue down, an operator raising the limit — and the run quota, a rolling 24 hours, frees its oldest runs as they age out. Tell the two apart by the body: a 429 whose body has a quota object is a quota, one without it is a throttle. quota carries kind, limit, used, remaining and resetsAt: the figures behind the sentence, and for the run quota the instant its oldest run ages out (#1258). Retry-After is sent on a quota only where there is such an instant (the run quota: the whole seconds, at least 1, until resetsAt); the case, review-queue and project quotas free only by an action, have resetsAt: null, and send no Retry-After. GET /v1/quotas reads the same figures without a refusal.

Media type application/json
One of:
object
error
required
string
Examples

A throttle: no `quota`; wait `Retry-After`

{
"error": "rate limit exceeded — slow down"
}
Retry-After
integer

Seconds until the window rolls over on a throttle; on a quota, until quota.resetsAt — sent only for the run quota, which has one