HTTP API¶

Generated from the repo root openapi.json with Widdershins. Do not edit this page by hand.

This page documents the HTTP surface exposed by mcp-v8 from the committed OpenAPI description.

CLI¶

List available CLI binary downloads for the running server version.¶

GET /api/cli

Each url is a direct download from this server. available: false means the binary was not embedded at build time (dev/local builds).

Example responses

200 Response

{
  "assets": [
    {
      "available": true,
      "platform": "string",
      "url": "string"
    }
  ],
  "version": "string"
}

Responses¶

Status	Meaning	Description	Schema
200	OK	CLI download index	CliIndex

Authentication: none.

Download the CLI binary for a specific platform directly from this server.¶

GET /api/cli/{platform}

The binary is embedded at build time and always matches the running server version. Returns 404 if the server was built without embedded binaries (dev/local builds).

Supported platforms: linux-x86_64, linux-aarch64, macos-aarch64.

Parameters¶

Name	In	Type	Required	Description
platform	path	string	true	Target platform (linux-x86_64

Example responses

404 Response

{
  "error": "string"
}

Responses¶

Status	Meaning	Description	Schema
200	OK	CLI binary (application/octet-stream)	None
404	Not Found	Unknown platform or binary not embedded	ApiError

Authentication: none.

Executions¶

Submit JavaScript code for asynchronous execution.¶

POST /api/exec

Returns immediately with an execution_id. Use GET /api/executions/{id} to poll status and GET /api/executions/{id}/output to read console output.

Two request encodings are accepted, selected by Content-Type: - application/json (or no Content-Type): a JSON ExecRequest body (the schema below). - any other type (e.g. application/javascript, text/plain): the raw request body is taken as the script source — i.e. a file upload (curl --data-binary @script.js). Optional heap, session, heap_memory_max_mb, and execution_timeout_secs may be passed as query-string parameters.

Body parameter

{
  "code": "string",
  "execution_timeout_secs": 0,
  "fs": "string",
  "heap": "string",
  "heap_memory_max_mb": 0,
  "session": "string",
  "tags": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters¶

Name	In	Type	Required	Description
body	body	ExecRequest	true	none

Example responses

202 Response

{
  "execution_id": "string"
}

Responses¶

Status	Meaning	Description	Schema
202	Accepted	Execution queued	ExecAccepted
400	Bad Request	Malformed request body	ApiError
415	Unsupported Media Type	Unsupported Content-Type (e.g. multipart/form-data)	ApiError
500	Internal Server Error	Internal error	ApiError

Authentication: none.

List all known executions (running and recently completed).¶

GET /api/executions

Example responses

200 Response

{
  "executions": [
    null
  ]
}

Responses¶

Status	Meaning	Description	Schema
200	OK	Execution list	ExecutionList
500	Internal Server Error	Internal error	ApiError

Authentication: none.

Get the status and result of an execution.¶

GET /api/executions/{id}

Parameters¶

Name	In	Type	Required	Description
id	path	string	true	Execution ID returned by POST /api/exec

Example responses

200 Response

{
  "completed_at": "string",
  "error": "string",
  "execution_id": "string",
  "fs": "string",
  "heap": "string",
  "result": "string",
  "started_at": "string",
  "status": "string"
}

Responses¶

Status	Meaning	Description	Schema
200	OK	Execution found	ExecutionInfo
404	Not Found	Execution not found	ApiError

Authentication: none.

Cancel a running execution.¶

POST /api/executions/{id}/cancel

Parameters¶

Name	In	Type	Required	Description
id	path	string	true	Execution ID to cancel

Example responses

200 Response

{
  "error": "string",
  "ok": true
}

Responses¶

Status	Meaning	Description	Schema
200	OK	Cancel accepted	CancelResult
400	Bad Request	Cannot cancel (e.g. already finished)	CancelResult

Authentication: none.

Read paginated console output from an execution.¶

GET /api/executions/{id}/output

Supports both line-based (line_offset / line_limit) and byte-based (byte_offset / byte_limit) pagination. Use has_more and next_line_offset / next_byte_offset to iterate.

Parameters¶

Name	In	Type	Required	Description
id	path	string	true	Execution ID
line_offset	query	integer(int64)	false	Return output starting at this line number (0-indexed).
line_limit	query	integer(int64)	false	Maximum number of lines to return.
byte_offset	query	integer(int64)	false	Return output starting at this byte offset.
byte_limit	query	integer(int64)	false	Maximum number of bytes to return.

Example responses

200 Response

{
  "data": "string",
  "end_byte": 0,
  "end_line": 0,
  "execution_id": "string",
  "has_more": true,
  "next_byte_offset": 0,
  "next_line_offset": 0,
  "start_byte": 0,
  "start_line": 0,
  "status": "string",
  "total_bytes": 0,
  "total_lines": 0
}

Responses¶

Status	Meaning	Description	Schema
200	OK	Output page	ExecutionOutput
404	Not Found	Execution not found	ApiError

Authentication: none.

Fs¶

List filesystem snapshot labels.¶

GET /api/fs/labels

Responses¶

Status	Meaning	Description	Schema
200	OK	Labels and their head CA ids	None

Authentication: none.

Create or repoint a filesystem snapshot label.¶

POST /api/fs/labels

Body parameter

{
  "ca_id": "string",
  "message": "string",
  "name": "string"
}

Parameters¶

Name	In	Type	Required	Description
body	body	FsLabelRequest	true	none

Responses¶

Status	Meaning	Description	Schema
200	OK	Label set	None

Authentication: none.

Resolve a label to its current head CA id.¶

GET /api/fs/labels/{label}

Parameters¶

Name	In	Type	Required	Description
label	path	string	true	Label name

Responses¶

Status	Meaning	Description	Schema
200	OK	Current head CA id	None
404	Not Found	Unknown label	None

Authentication: none.

Show the reflog for a label.¶

GET /api/fs/labels/{label}/log

Parameters¶

Name	In	Type	Required	Description
label	path	string	true	Label name
limit	query	integer	false	Return only the most recent N reflog entries (oldest-first). Omit for the full history.

Responses¶

Status	Meaning	Description	Schema
200	OK	Reflog entries, oldest first	None

Authentication: none.

Three-way merge two snapshots into a new one.¶

POST /api/fs/merge

Body parameter

{
  "base": "string",
  "ours": "string",
  "prefer": "string",
  "theirs": "string"
}

Parameters¶

Name	In	Type	Required	Description
body	body	FsMergeRequest	true	none

Responses¶

Status	Meaning	Description	Schema
200	OK	Merge ran — body has status=merged (ca_id) or status=conflict. Text files auto-merge at line level; each conflict carries kind plus, for text, diff3 markers and unified diffs.	None
400	Bad Request	Invalid CA id or prefer value	None

Authentication: none.

Advance a label to a CA id (reject-and-rebase by default).¶

POST /api/fs/push

Body parameter

{
  "ca_id": "string",
  "detach": true,
  "expected": "string",
  "force": true,
  "label": "string",
  "message": "string"
}

Parameters¶

Name	In	Type	Required	Description
body	body	FsPushRequest	true	none

Responses¶

Status	Meaning	Description	Schema
200	OK	Push advanced the label	None
409	Conflict	Rejected — the label moved since the caller pulled	None

Authentication: none.

Reset a label to an earlier CA id from its reflog.¶

POST /api/fs/reset

Body parameter

{
  "allow_unlogged": true,
  "ca_id": "string",
  "label": "string",
  "message": "string"
}

Parameters¶

Name	In	Type	Required	Description
body	body	FsResetRequest	true	none

Responses¶

Status	Meaning	Description	Schema
200	OK	Label reset	None
400	Bad Request	CA id not in reflog (and allow_unlogged not set)	None

Authentication: none.

Meta¶

Return the running server version.¶

GET /api/version

Responses¶

Status	Meaning	Description	Schema
200	OK	Server version	None

Authentication: none.

Schemas¶

ApiError

{
  "error": "string"
}

Generic error body.

Properties¶

Name	Type	Required	Restrictions	Description
error	string	true	none	none

CancelResult

{
  "error": "string",
  "ok": true
}

Result of a cancel request.

Properties¶

Name	Type	Required	Restrictions	Description
error	string¦null	false	none	none
ok	boolean	true	none	none

CliAsset

{
  "available": true,
  "platform": "string",
  "url": "string"
}

A single entry in the CLI download index.

Properties¶

Name	Type	Required	Restrictions	Description
available	boolean	true	none	Whether the binary is embedded in this server build.
platform	string	true	none	Platform identifier (e.g. linux-x86_64).
url	string	true	none	Download URL for this binary via the server itself.

CliIndex

{
  "assets": [
    {
      "available": true,
      "platform": "string",
      "url": "string"
    }
  ],
  "version": "string"
}

Index of available CLI binary downloads for the running server version.

Properties¶

Name	Type	Required	Restrictions	Description
assets	[CliAsset]	true	none	Available platform binaries.
version	string	true	none	Server (and CLI) version string, e.g. "0.1.0".

ExecAccepted

{
  "execution_id": "string"
}

Accepted response containing the new execution's ID.

Properties¶

Name	Type	Required	Restrictions	Description
execution_id	string	true	none	Unique identifier for the queued execution.

ExecRequest

{
  "code": "string",
  "execution_timeout_secs": 0,
  "fs": "string",
  "heap": "string",
  "heap_memory_max_mb": 0,
  "session": "string",
  "tags": {
    "property1": "string",
    "property2": "string"
  }
}

Request body for executing JavaScript code.

Properties¶

Name	Type	Required	Restrictions	Description
code	string	true	none	JavaScript (or TypeScript) source code to execute.
execution_timeout_secs	integer(int64)¦null	false	none	Per-execution timeout in seconds (overrides server default).
fs	string¦null	false	none	Filesystem snapshot handle to mount: a label name or 64-hex CA id. Independent of heap.
heap	string¦null	false	none	Serialised heap snapshot key to restore before execution.
heap_memory_max_mb	integer¦null	false	none	Per-execution V8 heap memory cap in megabytes.
session	string¦null	false	none	Session identifier used for tagging / logging.
tags	object¦null	false	none	Arbitrary key/value tags attached to the resulting heap snapshot.
» additionalProperties	string	false	none	none

ExecutionInfo

{
  "completed_at": "string",
  "error": "string",
  "execution_id": "string",
  "fs": "string",
  "heap": "string",
  "result": "string",
  "started_at": "string",
  "status": "string"
}

Detailed status of a single execution.

Properties¶

Name	Type	Required	Restrictions	Description
completed_at	string¦null	false	none	ISO-8601 timestamp when execution finished (absent while running).
error	string¦null	false	none	Error message (present when status is failed).
execution_id	string	true	none	none
fs	string¦null	false	none	Filesystem snapshot CA id produced after execution (when a mount was attached), independent of the heap.
heap	string¦null	false	none	Heap snapshot key produced after execution.
result	string¦null	false	none	Final return value serialised to JSON (present when status is completed).
started_at	string	true	none	ISO-8601 timestamp when execution started.
status	string	true	none	Current status: running, completed, failed, cancelled, timed_out.

ExecutionList

{
  "executions": [
    null
  ]
}

List of execution summaries.

Properties¶

Name	Type	Required	Restrictions	Description
executions	[any]	true	none	none

ExecutionOutput

{
  "data": "string",
  "end_byte": 0,
  "end_line": 0,
  "execution_id": "string",
  "has_more": true,
  "next_byte_offset": 0,
  "next_line_offset": 0,
  "start_byte": 0,
  "start_line": 0,
  "status": "string",
  "total_bytes": 0,
  "total_lines": 0
}

A page of console output from an execution.

Properties¶

Name	Type	Required	Restrictions	Description
data	string	true	none	Text content for the requested window.
end_byte	integer(int64)	true	none	Last byte offset in this page (exclusive).
end_line	integer(int64)	true	none	Last line number in this page (exclusive).
execution_id	string	true	none	none
has_more	boolean	true	none	Whether more output is available beyond this page.
next_byte_offset	integer(int64)	true	none	Byte offset to use for the next page (pass as byte_offset).
next_line_offset	integer(int64)	true	none	Line offset to use for the next page (pass as line_offset).
start_byte	integer(int64)	true	none	First byte offset in this page.
start_line	integer(int64)	true	none	First line number in this page (0-indexed).
status	string	true	none	Execution status at the time of this query.
total_bytes	integer(int64)	true	none	Total bytes written so far.
total_lines	integer(int64)	true	none	Total lines written so far.

ExecutionSummary

{
  "completed_at": "string",
  "execution_id": "string",
  "started_at": "string",
  "status": "string"
}

A brief summary of a single execution (used in list responses).

Properties¶

Name	Type	Required	Restrictions	Description
completed_at	string¦null	false	none	none
execution_id	string	true	none	none
started_at	string	true	none	none
status	string	true	none	none

FsLabelRequest

{
  "ca_id": "string",
  "message": "string",
  "name": "string"
}

Request body for POST /api/fs/labels (create or repoint a label).

Properties¶

Name	Type	Required	Restrictions	Description
ca_id	string	true	none	none
message	string¦null	false	none	Optional human note recorded on the reflog entry, like a commit message.
name	string	true	none	none

FsLogQuery

{
  "limit": 0
}

Optional query parameters for a label reflog read.

Properties¶

Name	Type	Required	Restrictions	Description
limit	integer¦null	false	none	Return only the most recent N reflog entries (oldest-first). Omit for the full history.

FsMergeRequest

{
  "base": "string",
  "ours": "string",
  "prefer": "string",
  "theirs": "string"
}

Request body for POST /api/fs/merge.

Properties¶

Name	Type	Required	Restrictions	Description
base	string¦null	false	none	The common ancestor both sides diverged from. Omit for a 2-way merge.
ours	string	true	none	One side of the merge (CA id, e.g. an execution's fs result).
prefer	string¦null	false	none	ours or theirs to auto-resolve conflicts; omit to report them.
theirs	string	true	none	The other side (CA id).

FsPushRequest

{
  "ca_id": "string",
  "detach": true,
  "expected": "string",
  "force": true,
  "label": "string",
  "message": "string"
}

Request body for advancing a filesystem snapshot label (POST /api/fs/push).

Properties¶

Name	Type	Required	Restrictions	Description
ca_id	string	true	none	The CA id (hex) to point the label at — typically the fs value from a completed execution.
detach	boolean	false	none	Do not touch any label; just echo the CA id back.
expected	string¦null	false	none	The head the caller pulled. The push is rejected if the label has moved since (reject-and-rebase). Ignored when force is true.
force	boolean	false	none	Override the conflict check and move the label unconditionally.
label	string¦null	false	none	Label to advance. Omit only when detach is true.
message	string¦null	false	none	Optional human note recorded on the reflog entry, like a commit message.

FsResetRequest

{
  "allow_unlogged": true,
  "ca_id": "string",
  "label": "string",
  "message": "string"
}

Request body for POST /api/fs/reset.

Properties¶

Name	Type	Required	Restrictions	Description
allow_unlogged	boolean	false	none	Allow resetting to a CA id that is not in the label's reflog.
ca_id	string	true	none	none
label	string	true	none	none
message	string¦null	false	none	Optional human note recorded on the reflog entry, like a commit message.

OutputQuery

{
  "byte_limit": 0,
  "byte_offset": 0,
  "line_limit": 0,
  "line_offset": 0
}

Optional pagination query parameters for console output.

Properties¶

Name	Type	Required	Restrictions	Description
byte_limit	integer(int64)¦null	false	none	Maximum number of bytes to return.
byte_offset	integer(int64)¦null	false	none	Return output starting at this byte offset.
line_limit	integer(int64)¦null	false	none	Maximum number of lines to return.
line_offset	integer(int64)¦null	false	none	Return output starting at this line number (0-indexed).