Skip to content

Add a source to a mission

POST
/v1/missions/{id}/sources
curl --request POST \
--url https://beta-api.plune.ai/v1/missions/example/sources \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "kind": "openapi", "ref": "https://shop.example.com/openapi.json", "title": "Shop API", "version": "2026-11-01" }'

A link the testing reads: a page (url), an API description (openapi), a repository (repo) or a ticket (ticket), with a title and the version read; or an MCP server to test (mcp, #2463): its address or command in ref and, in mcp, the names of the environment variables that hold its secrets. A source that holds a secret instead - a headers or authorization field, an env with values, a token in the address or on the command line - is a 400 source_holds_secret that names where, never what. An mcp source puts its server in the project’s MCP catalog at once (GET /v1/mcp-servers): a server of the same name is linked (missionSourceId) and keeps its trust; with none, a person’s source makes one with source: mission and trust: derived, and an agent’s (X-Plune-Session) makes none - nothing enters the catalog without a person (ADR 0010). The name is the source’s title, else the host of the address, else the first word of the command that is not a launcher or a flag. Taking the source off keeps the server, unlinked. At most 100 sources a mission (409).

id
required
string

The mission’s id

Media type application/json
object
kind
required
string
Allowed values: url openapi repo ticket mcp
ref
required

The link, http or https only; for mcp the server’s address (http) or its command line (stdio)

string
>= 1 characters <= 2048 characters
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
title

What the source is, as a person names it

string
>= 1 characters <= 200 characters
version

The version read

string
>= 1 characters <= 200 characters
Example
{
"kind": "openapi",
"ref": "https://shop.example.com/openapi.json",
"title": "Shop API",
"version": "2026-11-01"
}

The source

Media type application/json
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-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 an mcp source that holds a secret (source_holds_secret, with the path of the field, never its value)

Media type application/json
object
error
required
string
Example
{
"error": "an MCP source names the environment variable that holds a secret (mcp.tokenEnv, mcp.env), never the secret: mcp.env (a map of values: name the variables, as a list)",
"code": "source_holds_secret",
"path": "mcp.env (a map of values: name the variables, as a list)"
}

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"
}

The mission holds the most sources it can

Media type application/json
object
error
required
string
Example
{
"error": "a mission holds at most 100 sources: take one off first"
}

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

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

Seconds until the window rolls over