API Documentation

Reference for all available REST endpoints.

All API requests (except `/version` and `/auth/login`) require a Bearer token in the Authorization header. All paths shown are relative to the API host, and prefixed with /api/v0.

Authentication & Global

Description:

Get API version information.

Parameters / Request Body:

None

Description:

Get current authenticated user.

Parameters / Request Body:

Requires Bearer token in Authorization header.

Description:

Login with a Pinecone API key to get a JWT token.

Parameters / Request Body:

JSON Body: { "api_key": "YOUR_PINECONE_KEY" }

Description:

Get global task statistics.

Parameters / Request Body:

Requires Bearer token.

Core Contexts

Description:

List all contexts owned by the authenticated user.

Parameters / Request Body:

None

Description:

Create a new context. Name must be 3-64 chars, lowercase alphanumeric and hyphens, starting with a letter and ending with a letter or digit.

Parameters / Request Body:

JSON Body: { "name": "my-context", "slug": "my-context", "description": "Optional desc", "guardrails": "Optional instructions" }

Description:

Get details for a specific context.

Parameters / Request Body:

Path parameter: id (UUID)

Description:

Update context fields.

Parameters / Request Body:

JSON Body: { "name": "new-name", "description": "...", "guardrails": "..." }

Description:

Delete a context. Fails if active tasks exist.

Parameters / Request Body:

Path parameter: id (UUID)

Context Operations

Description:

Run a query against the context's knowledge base.

Parameters / Request Body:

JSON Body: { "instruction": "Your query", "background": true, "timeout_seconds": null }

Description:

Trigger curation of source files into the Pinecone index. Only one curate task can run at a time.

Parameters / Request Body:

No body required.

Description:

Start the autonomous build pipeline to tune curate.py and query.py against test cases.

Parameters / Request Body:

JSON Body: { "force": true, "eval_pass_rate_threshold": 0.85, "retrieval_p90_latency_ms": null, "build_timeout_seconds": 3600, "max_tool_turns": 200, "max_iterations": 20 }

Description:

Get the current build status for this context.

Parameters / Request Body:

None

Source Management (/source)

Description:

Upload raw files (max 250MB each) to the source directory.

Parameters / Request Body:

Multipart form data: files=[]. Optional query: ?path=subfolder

Description:

List files in the root source directory.

Parameters / Request Body:

None

Description:

List files in a source subdirectory.

Parameters / Request Body:

Path parameter: path (string)

Description:

Read/download a source file.

Parameters / Request Body:

Path parameter: path (string)

Description:

Delete a source file or directory.

Parameters / Request Body:

Path parameter: path (string)

Knowledge Management (/knowledge)

Description:

List files in the root knowledge directory.

Parameters / Request Body:

None

Description:

List files in a knowledge subdirectory.

Parameters / Request Body:

Path parameter: path (string)

Description:

Read a knowledge file.

Parameters / Request Body:

Path parameter: path (string)

Eval Management (/evals)

Description:

List all eval cases for this context.

Parameters / Request Body:

None

Description:

Create a new eval case.

Parameters / Request Body:

JSON Body: { "input": "Your query", "expected_output": "Expected answer (optional)" }

Description:

Update an existing eval case.

Parameters / Request Body:

JSON Body: { "input": "Updated query", "expected_output": "Updated answer" }

Description:

Delete an eval case.

Parameters / Request Body:

Path parameter: eval_id (UUID)

Code Management (/code)

Description:

List files in the root code directory.

Parameters / Request Body:

None

Description:

List files in a code subdirectory.

Parameters / Request Body:

Path parameter: path (string)

Description:

Read a code file.

Parameters / Request Body:

Path parameter: path (string)

Description:

Get the build instructions (build.md) for this context.

Parameters / Request Body:

Returns: { "content": "..." }

Description:

Update the build instructions (build.md). Owner only.

Parameters / Request Body:

JSON Body: { "content": "..." }

Task Management (/tasks)

Description:

List tasks for this context. Supports filtering by workflow, state, and free-text search.

Parameters / Request Body:

Query: workflow, state, q, limit (default 30), offset, page

Description:

Get a specific task by ID.

Parameters / Request Body:

Path parameter: task_id (UUID)

Description:

Cancel a task. Sets state to stopping and queues container termination.

Parameters / Request Body:

Optional JSON Body: { "reason": "user" }

Description:

Get CPU, memory, and token statistics for a specific task.

Parameters / Request Body:

Path parameter: task_id (UUID)

Description:

List files in the task workspace root.

Parameters / Request Body:

Query: offset, limit

Description:

List files in a task workspace subdirectory.

Parameters / Request Body:

Path parameter: path (string). Query: offset, limit

Description:

Read a file from the task workspace (live or archived).

Parameters / Request Body:

Path parameter: path (string)

Description:

Get metadata for a task file.

Parameters / Request Body:

Path parameter: path (string)

Description:

Delete a file from a live task workspace.

Parameters / Request Body:

Path parameter: path (string)

Task Runtime (Internal)

Description:

Called by task container on startup to mark itself as running.

Parameters / Request Body:

None

Description:

Called by task runtime to report a fatal error.

Parameters / Request Body:

JSON Body: { "error": "Error message" }

Description:

Called by task runtime to report output, steps, and token usage.

Parameters / Request Body:

JSON Body with output, steps, step_updates, prompt_tokens_delta, completion_tokens_delta.