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.

Body parameter

{
  "code": "string",
  "execution_timeout_secs": 0,
  "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
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",
  "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.

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,
  "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).
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",
  "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
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

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).