Skip to content

Upload a file as a source of a mission

POST
/v1/missions/{id}/files
curl --request POST \
--url https://beta-api.plune.ai/v1/missions/example/files \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "checkout-rules.md", "text": "# Checkout rules\n\n- A coupon applies once.\n", "version": "rev 12" }'

A file of the project’s own (#2188): text, Markdown or JSON, told by its name, at most 1048576 bytes (1 MiB) - its text in the body. It becomes a file source named by the file; its size and type are on the mission, its text is read with GET /v1/missions/{id}/sources/{sourceId}/file. It counts among the 100 sources of a mission (409). A file taken off a mission is not put back from the feed: upload it again.

id
required
string

The mission’s id

Media type application/json
object
name
required

The file’s name: .txt, .md, .markdown or .json, which says its type

string
>= 1 characters <= 200 characters
text
required

The file’s text, at most 1048576 bytes (1 MiB) in UTF-8: over it is a 413 that names the limit

string
title

What the source is, as a person names it; the file’s name when left out

string
>= 1 characters <= 200 characters
version

The version of the document, as its owner names it

string
>= 1 characters <= 200 characters
Example
{
"name": "checkout-rules.md",
"text": "# Checkout rules\n\n- A coupon applies once.\n",
"version": "rev 12"
}

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": "file",
"ref": "checkout-rules.md",
"title": "checkout-rules.md",
"version": "rev 12",
"addedBy": "6f1c2b3a-0000-4000-8000-0000000000a2",
"createdAt": "2026-11-04T09:10:00.000Z",
"bytes": 14336,
"mediaType": "text/markdown"
}

Invalid JSON or body, a file that is not text, Markdown or JSON (file_type), or a text with a NUL character or an unpaired surrogate (file_not_text)

Media type application/json
object
error
required
string
Example
{
"error": "a source file is text, Markdown or JSON: .txt, .md, .markdown or .json",
"code": "file_type"
}

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

The file is over 1 MiB (file_too_large, with maxBytes)

Media type application/json
object
error
required
string
Example
{
"error": "a source file is at most 1048576 bytes (1 MiB); this one is 3355443",
"code": "file_too_large",
"maxBytes": 1048576
}

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