Skip to content

API reference

HTTP API

The mux API is JSON over HTTPS. It is what muxcode, the MCP server and the web app use to reach a workspace’s code index, its repositories, its agent memory and its sandboxes, and anything you build can use it the same way.

Every path below is under the base URL https://usemux.com/api.

Send a workspace key

A workspace key is a bearer token: Authorization: Bearer hk_live_…. Each key belongs to exactly one workspace and carries a role, and it can never do more than the person who minted it can do today. A key whose owner loses access stops working with them.

Workspace owners mint keys in the app under Access keys, in the sidebar. A key is shown once, when it is minted; mux keeps only its hash.

Roles, from least to most: viewer, agent, editor, owner. Each route below names the least role it needs.

The web app calls the same routes with the signed-in person’s session cookie instead of a key. Routes marked signed-in person accept only that: a key, however senior, is refused with 403 human_gate.

Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/workspace \
-H "Authorization: Bearer $MUX_API_KEY"

The error shape

mux answers with a conventional status code and, for every error, one JSON envelope: a stable code to branch on and a message written to be shown to a person.

  • 400 validation_error - the body or a parameter is not what the route accepts. invalid_json when the body is not JSON at all.
  • 401 unauthenticated - no key or session, or a key that is revoked or expired.
  • 402 - the plan does not include a sandbox or Clef (plan_refused), or a cap is spent (cap, with the cap body under Sandboxes).
  • 403 forbidden - your role is below the route’s. human_gate when the route needs a signed-in person. plan_refused and plan_limit when the plan does not include it.
  • 404 not_found - no such thing, or one your credential cannot see. A workspace in another organization answers 404, never 403, so a key cannot learn what exists elsewhere.
  • 409 - the request conflicts with the workspace’s state, such as no_repositories, refresh_in_progress or team_member.
  • 422 - the request is well formed but cannot be done: jev_request_budget when a Clef call cannot fit before its window resets, idempotency_conflict when an Idempotency-Key comes back with another body, invalid_member when a grant names someone outside the organization.
  • 429 - a rate limit; see below. Clef also answers 429 jev_busy while calls still pending hold the room a new one needs. Code search and memory answer 429 search_hours_spent past the month’s search and memory hours, and get_context 429 context_rate_limited past 60 calls an hour.
  • 5xx - mux or a service behind it did not answer. 503 index_unavailable is safe to retry.
Response 404
{
"error": {
"code": "not_found",
"message": "Vault not found."
}
}

Two meters per organization

Every /v1 request draws from two meters kept per organization: a per-minute burst bucket and a monthly ceiling by UTC calendar month. Each response reports both.

  • X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds) for the burst bucket.
  • X-Quota-Limit and X-Quota-Remaining for the month.

Past either meter the answer is 429 with Retry-After, and scope names the meter. burst clears within the minute. monthly clears at the start of the next UTC month, so do not retry it in a loop. This one answer is a flat body rather than the error envelope.

Device sign-in is limited by address instead, and refuses a start when the limiter cannot answer.

Plan Workspaces Repositories indexed Refresh Code search Search and memory hours/month Requests/min Requests/month
Hobby 1 none (1 chosen) none no 0 30 50,000
Pro 1 20 on push yes 50 120 500,000
Pro+ 25 50 on push yes 300 300 2,000,000
Ultra 65 125 on push yes 750 750 5,000,000

A live trial has Pro’s figures. Workspaces are counted per organization. Beside their own, a person may create one team organization on Pro or a trial, 25 on Pro+, 65 on Ultra, and none on Hobby. A team organization has no price and no row of its own: its requests a minute and a month and the repositories it indexes are those of the best plan among its members (an owner’s plan counts for as many of their team organizations as it includes, picked with PUT /v1/team-workspaces/picks, else the oldest), it holds any number of workspaces, and each member’s sandboxes, Triage and Clef come from their own plan. A team organization has no search and memory hours of its own: each member spends their own plan’s, counted together across their workspaces and teams, and a Hobby member gets 403 plan_refused. They count the time code search, get_context and memory keep the index awake, plus 10 idle minutes after each call, with overlapping calls counted once.

Response 429
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1727000060
{
"error": "Rate limit exceeded",
"scope": "burst",
"retryAfter": 12
}

A workspace holds the repositories you index, the people and keys that can reach it, and its sandbox runs. In the API a workspace is a vault, and its id is the vaultId in every path.

Retrieve a workspace

GET /v1/vaults/:vaultId/workspace

Who can call itviewer

Describes the workspace a key or session reaches, and what its plan lets a client offer. Read capabilities before searching: a workspace without semantic has no code search, and its searches answer 403 plan_refused.

Returns

plan string
free (Hobby), pro, proplus, ultra or team.
role string
The caller’s role in this workspace.
trial object | null
The caller’s trial, in the device sign-in’s shape but never with a keychainToken; null when they have none.
meters object
Where the caller stands against their caps, in the device sign-in’s shape.
payment object | null
A charge for the caller’s own plan that failed and is still unpaid: { plan, failedAt, stopsAt }, the plan it was for and, in milliseconds, when it failed and when that plan stops or stopped. The plan keeps working until stopsAt, a day after the failure, and plan reads free from then on. null when nothing is owed, or when a key rather than a person is asking.
capabilities object
semantic, structuralSearch and repositoryFilters. semantic is false on Hobby.
index object
The number of repositories indexed, file and chunk counts, lastSuccessAt in milliseconds, and the embeddingVersion the index was built with.
managementUrl string
Where the workspace is managed in the app.
Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/workspace \
-H "Authorization: Bearer $MUX_API_KEY"
Response 200
{
"managementUrl": "https://usemux.com/app/workspaces?corpus=01J9Z3K8QG",
"organizationId": "org_2Yc81",
"workspaceName": "Acme",
"corpusId": "01J9Z3K8QG",
"corpusName": "Code corpus",
"plan": "pro",
"role": "agent",
"capabilities": {
"semantic": true,
"structuralSearch": true,
"repositoryFilters": true
},
"index": {
"embeddingVersion": "@cf/google/embeddinggemma-2",
"repositories": 2,
"files": 1234,
"chunks": 5678,
"lastSuccessAt": 1727000000000
}
}

List workspaces

GET /v1/vaults

Who can call itany key or session

A signed-in person gets every workspace they hold a grant on, oldest first, with their role in each. A key gets its one workspace, without role, or an empty list once that workspace is deleted.

Query parameters

deleted 1
Signed-in person only: list the deleted workspaces you own instead. Each can be restored for 30 days with POST /v1/vaults/:vaultId/restore.
Request
curl https://usemux.com/api/v1/vaults \
-H "Authorization: Bearer $MUX_API_KEY"
Response 200
[
{
"id": "01J9Z3K8QF",
"orgId": "org_2Yc81",
"name": "Acme",
"slug": "acme",
"createdAt": 1726500000000
}
]

One route answers every question you can ask the index. The body names an operation and its arguments: seven operations, which are seven of the MCP server’s nine tools. The other two are record_context_outcome (POST /corpus/outcomes) and workspace_memory (POST /memory/query).

Query the index

POST /v1/vaults/:vaultId/corpus/query

Who can call itviewer

Every result carries repository, path, line, endLine, excerpt and the headSha it was read at; search_code results also carry language, and search_code and ask_code results a score (grep_code matches have none). The body is capped at 16 KiB.

Body

organizationId string required
The organization the workspace belongs to. Any other answers 404 not_found.
operation string required
One of corpus_status, list_repositories, grep_code, search_code, ask_code, get_context or trace_code.
arguments object
The operation’s arguments; see Operations below.
record boolean
false keeps the search out of the workspace’s analytics. Defaults to true.

Operations

corpus_status no arguments
Whether the workspace is indexed, its repositories and their state, the workspace’s plan and its limits, and search: whether the caller’s own plan includes code search. In a team the plan reads team for every member, and search is what decides. Read from stored state; it never wakes the index.
list_repositories no arguments
{repositories}, each with its name and indexed headSha.
grep_code pattern · path, language, repository
A structural match against the syntax tree, not a text search. In a pattern a backslash marks a placeholder: foo(\X) is a call with one argument, foo(\(ARGS*\)) a call with any number. Answers {results, truncated}.
search_code query · limit, repository, language, path
Results ranked by meaning, so a search can find code that never uses its words. A path keeps one file or folder: inside repository when you name one, and otherwise starting with the repository, as owner/name/src. A path that names no repository is refused with 400. Pro, Pro+ and a trial.
ask_code query
The passages that bear on a question, as grounding. It does not write the answer: answer is null, and your model reads the passages. Pro, Pro+ and a trial.
trace_code repository, path · symbol, limit
One file on the code graph: what it defines, imports, is importedBy, its tests and what it is testedBy, the routes it calls and is called from, and its owners.
get_context task · repositories, revisions, changedPaths, tokenBudget, freshness
One context packet for a task; see Context packets.

query caps at 4,000 characters, pattern at 2,000, path at 400 (relative, no ..), repository at 200 as owner/name, language at 100. symbol is one plain identifier, and limit runs from 1 to 50.

Refusals

403 plan_refused Hobby
Every operation but corpus_status: “Code search is included with Pro and Pro+, and during a trial.”
429 search_hours_spent month
Every operation but corpus_status, once the plan of the person behind the call has used its search and memory hours, counted across their workspaces and teams: “This plan’s 50 hours of search and memory for the month are used, across its workspaces and teams; they come back on 1 December (UTC).” It clears when the UTC month turns.
429 context_rate_limited Retry-After
get_context past 60 calls an hour for the workspace. The index is not woken. Retry after Retry-After seconds.
409 no_repositories nothing chosen
grep_code, search_code and ask_code before any repository is chosen. corpus_status and list_repositories still answer 200.
503 index_unavailable retry
The index did not answer, or is waking from rest. Retry; corpus_status keeps answering.
503 graph_unavailable trace_code
The index has not written its code graph at the current commit yet. Refresh, then retry.
503 index_warming get_context
The index is starting after a rest. Retry after retryAfterSeconds, also sent as Retry-After. An allow_stale retry can meet it too.
Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/corpus/query \
-H "Authorization: Bearer $MUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"organizationId": "org_2Yc81",
"operation": "search_code",
"arguments": {
"query": "retry a failed upload",
"repository": "acme/api",
"limit": 2
}
}'
Response 200
{
"results": [
{
"repository": "acme/api",
"path": "src/uploads/retry.ts",
"line": 14,
"endLine": 41,
"language": "typescript",
"score": 0.82,
"excerpt": "export async function retryUpload(job: UploadJob) {\n …",
"headSha": "9f3c2a1e4b7d…"
}
]
}
grep_code, Response 200
{
"results": [
{
"repository": "acme/api",
"path": "src/ledger.ts",
"line": 88,
"endLine": 88,
"excerpt": "split(total, accounts)",
"headSha": "9f3c2a1e4b7d…"
}
],
"truncated": false
}

Read and update agent memory

POST /v1/vaults/:vaultId/memory/query

Who can call itviewer to read; agent to write

Each workspace has a shared workspace memory repo and a private personal repo for each member. The key issuer or signed-in member determines whose private repo is used. GET /v1/vaults/:vaultId/memory returns both MEMORY.md entry points and their Git revisions for session startup.

Body

operation string required
status, list, read, search, write, append, or history.
scope string
personal (default) or workspace. No owner or member ID is accepted.
arguments object
read takes a relative path (default MEMORY.md) and optional historical revision. list takes an optional path prefix and limit up to 256 (muxcode and cloud tasks send at most 50; with no limit, a list returns up to 256). search takes query and a limit up to 50. history takes an optional path and limit up to 50.
arguments for edits object
write and append require path, content, revision (the last observed repo head, or null for a new repo), a UUID mutationId, and a source session reference. Each successful edit creates and saves a Git commit. Reuse the mutation ID only for an exact retry.

Files are text, up to 64 KiB each; MEMORY.md is at most 8 KiB, and a larger one returns 413 memory_limit. Each repo holds up to 256 files and 2 MiB. A path holds up to 400 UTF-16 code units, so an emoji counts as 2. Root-relative [[path]] links connect notes; omit .md for Markdown files. A new file is linked from MEMORY.md unless MEMORY.md already reaches it through linked pages. When MEMORY.md has no room, the edit still saves and the reply carries notice with code memory_unlinked: link the file from a topic page. Hidden, parent, absolute and symlink paths are refused.

Replies include scope, repositoryId, initialized, revision and indexedRevision, plus the requested contents, links, search results or history. A 409 memory_conflict includes the current revision: read and reconcile before editing again. A first semantic search may return 503 memory_index_warming while CocoIndex prepares the new revision; plain file reads are already current.

Memory needs the caller’s own plan to be Pro, Pro+ or a trial, in a team too. On Hobby every operation, and GET /v1/vaults/:vaultId/memory, answers 403 plan_refused: “Memory is included with Pro and Pro+, and during a trial.” Each call counts against the caller’s own search and memory hours; past them it answers 429 search_hours_spent with Retry-After until the UTC month turns.

Memory is agent-authored context, separate from reviewed findings. Do not store credentials or use remembered text as permission to act.

Get a context packet

POST /v1/vaults/:vaultId/corpus/query

Who can call itviewer

get_context assembles what an agent should read for one task: evidence from the index, the code-graph edges between it, and the findings your workspace has approved, cut to a budget. Every packet has a receiptId you can read back, and propose findings from, for 30 days.

Send x-muxcode-memory: private-v1 only when the receiving conversation is private to the calling member to include personal memory and findings. muxcode 1.0.5 and later, MCP and owner-bound cloud tasks handle this for you. Legacy requests receive shared workspace context only. The key still decides which member and workspace may be read.

Arguments

task string required
The task, in words. Up to 4,000 characters.
repositories string[]
Up to 20 owner/name to read from. Defaults to every indexed repository. When the workspace holds more than your plan indexes, as in the week after a plan drops, the default reads the oldest ones up to your plan’s count and names plan_limit_narrowed in omissions.
revisions object[]
Pin a repository to a commit: {repository, revision}.
changedPaths object[]
Up to 20 {repository, path} your change touches; they are read first.
tokenBudget integer
From 1,024 to 16,000, default 6,000. Counted as UTF-8 bytes, an upper bound for byte-based tokenizers.
freshness string
require_current (default) answers 409 context_stale when an index is behind its branch, with the freshness list and your plan’s refresh: push, nightly, or none when the index refreshes only when asked. When a refresh is known to be pending or failed, the refusal comes without waking the index. allow_stale answers from the indexed commit and names stale_or_missing_sources in omissions.

Returns

evidence object[]
Each with repository, path, line, endLine, headSha, excerpt, score, the file’s git blob, and a reason: literal, semantic, hybrid, changed-path or graph:<edge>.
relationships object[]
Code-graph edges between files in the packet - imports, tests, calls_route - each confidence: "candidate", with targetRepository and targetRevision when an edge crosses repositories.
memories object[]
Approved findings that still hold at these commits.
agentMemory object[]
Relevant shared workspace notes and the caller’s private notes. Each entry identifies scope, revision, indexedRevision, an entrypoint and ranked evidence, with authority: "agent-authored". Memory uses at most a third of the packet budget. It is also available before a code repository is selected.
omissions string[]
What was left out and why: token_budget, semantic_search_not_in_plan, lexical_unavailable, changed_path_unavailable, graph_unavailable, invalid_or_out_of_scope_evidence, no_evidence, plan_limit_narrowed, and for memory memory_entrypoint_truncated, memory_index_warming, memory_index_busy, memory_search_unavailable and memory_unavailable.
freshness object[]
Per repository: the expected and indexed revision, and current, stale, missing or unknown.
Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/corpus/query \
-H "Authorization: Bearer $MUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"organizationId": "org_2Yc81",
"operation": "get_context",
"arguments": {
"task": "Add rate limiting to the public API",
"repositories": ["acme/api"],
"tokenBudget": 6000
}
}'
Response 200
{
"version": "context-v2",
"freshness": [
{
"repository": "acme/api",
"expectedRevision": "9f3c2a1e4b7d…",
"indexedRevision": "9f3c2a1e4b7d…",
"state": "current"
}
],
"evidence": [
{
"repository": "acme/api",
"path": "src/middleware/auth.ts",
"line": 1,
"endLine": 60,
"headSha": "9f3c2a1e4b7d…",
"excerpt": "export const requireKey = …",
"score": 0.77,
"reason": "hybrid"
}
],
"relationships": [],
"memories": [],
"omissions": ["token_budget"],
"tokenBudget": 6000,
"receiptId": "5b0f6c1e-…",
"retrievalMs": 412,
"expiresAt": 1729592000000
}

Propose a finding

POST /v1/vaults/:vaultId/corpus/outcomes

Who can call itagent

A finding is one sentence your agent learned, tied to the commit and files it rests on. Proposed from a context packet’s receipt, it waits for a signed-in owner to approve it with POST /corpus/memories/:memoryId/approve or /retire; a key never can. After each refresh an approved finding moves to the new commit while every file it cites is unchanged, and becomes outdated when one changes.

GET /corpus/memories lists findings: an owner sees all, others their own and the approved ones. GET /corpus/receipts/:receiptId returns a packet to whoever asked for it, and GET /corpus/trace gives a signed-in owner the 25 newest packets and the week’s figures.

Body

receiptId string required
Your own receipt, unexpired.
repository string required
owner/name.
revision string required
A headSha from that receipt.
statement string required
The finding, up to 2,000 characters.
scope string
personal or workspace.
retentionDays integer
1 to 30, default 7.
paths string[]
1 to 20 files the receipt read that the finding rests on. Defaults to every file it read there.
Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/corpus/outcomes \
-H "Authorization: Bearer $MUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"receiptId": "5b0f6c1e-…",
"repository": "acme/api",
"revision": "9f3c2a1e4b7d…",
"statement": "Every public route passes requireKey before its handler.",
"scope": "workspace",
"paths": ["src/middleware/auth.ts"]
}'
Response 201
{
"id": "01J9Z4B2M1",
"status": "proposed"
}

The repositories a workspace indexes come from its GitHub installation. An owner connects GitHub in the browser; after that, editors choose what to index.

List indexed repositories

GET /v1/vaults/:vaultId/repositories

Who can call itviewer

The workspace’s selection with each repository’s index state, the GitHub connection, and the plan’s limit.

Each repository

status string
mirroring, refreshing, fresh, stale or failed.
indexedSha string | null
The commit the index was built from. latestSha is the branch’s newest, and stale is true when they differ.
files, chunks integer
What the index holds for it.
error string | null
Why the last index failed, in words.
waiting boolean
failed only because another index run held the index; the next run starts it.
planLocked boolean
failed only because the plan has no code search (Hobby): the choice is kept and is indexed once the workspace has a plan that searches. False once the plan searches, while the row waits for its first index.
Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/repositories \
-H "Authorization: Bearer $MUX_API_KEY"
Response 200
{
"github": {
"configured": true,
"connected": true,
"account": "acme",
"installUrl": null
},
"canManage": false,
"plan": "pro",
"limits": { "repositories": 20 },
"refresh": "push",
"repositories": [
{
"repository": "acme/api",
"branch": "main",
"status": "fresh",
"indexedSha": "9f3c2a1e4b7d…",
"latestSha": "9f3c2a1e4b7d…",
"stale": false,
"indexedAt": 1727000000000,
"files": 120,
"chunks": 900,
"error": null
}
]
}

Choose repositories to index

PUT /v1/vaults/:vaultId/repositories

Who can call iteditor

The body is the whole selection. A repository left out is deselected, and its mirror and index entries are removed. A new one starts as mirroring. On Hobby the selection is saved but nothing is indexed: a new repository shows failed with planLocked true and the error “Code search is included with Pro and Pro+, and during a trial.”, and is indexed by a five-minute check after the workspace gets Pro, Pro+, Team or a trial. Each check looks at 100 waiting workspaces, a different 100 each time, so with many waiting it can take several checks.

Body

repositories object[] required
Each {repository, branch}. branch defaults to the repository’s default branch.

Refusals

404 repository_not_granted GitHub
The installation does not grant that repository.
403 plan_limit plan
More repositories than the plan allows: one on Hobby, 20 on Pro, 50 on Pro+. The count also holds across every workspace a person owns: past it, the refusal carries meter owned_repositories when the total is yours, or owner_repositories when it is this workspace’s owner’s, and the plan’s limit.
409 github_not_connected GitHub
Connect GitHub first.
409 selection_changed race
Another save of this workspace landed while this one ran and took it past the plan’s count. Nothing of this save was written; read the list and save again.
Request
curl -X PUT https://usemux.com/api/v1/vaults/01J9Z3K8QF/repositories \
-H "Authorization: Bearer $MUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"repositories": [
{ "repository": "acme/api", "branch": "main" },
{ "repository": "acme/web" }
]
}'
Response 200
{
"repositories": [
{ "repository": "acme/api", "branch": "main", "status": "fresh", "…": "…" },
{ "repository": "acme/web", "branch": "main", "status": "mirroring", "…": "…" }
]
}

List what GitHub grants

GET /v1/vaults/:vaultId/github/repositories

Who can call iteditor

Every repository the GitHub installation grants, archived ones excluded, marking those already selected. Use it to offer a choice before PUT /repositories.

Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/github/repositories \
-H "Authorization: Bearer $MUX_API_KEY"
Response 200
{
"account": "acme",
"repositories": [
{
"repository": "acme/api",
"defaultBranch": "main",
"private": true,
"language": "TypeScript",
"sizeKb": 1234,
"selected": true
}
]
}

Refresh the index

POST /v1/vaults/:vaultId/corpus/refresh

Who can call iteditor

Re-indexes every selected repository, or the one you name. On Pro, Pro+, the trial and team workspaces, a push to an indexed branch starts this by itself. A refresh that fails for a moment is tried again after 5, 10 and 20 minutes.

Body

repository string
owner/name. Omit it to refresh everything.

Refusals

403 plan_refused Hobby
“Code search is included with Pro and Pro+, and during a trial.”
409 refresh_in_progress busy
A refresh is already running.
429 rate_limited Retry-After: 60
A refresh was asked for less than a minute ago.
429 index_hours_spent Retry-After: month end
The workspace has used its index hours for the month. The nightly refresh still brings it up to date.
Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/corpus/refresh \
-H "Authorization: Bearer $MUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "repository": "acme/api" }'
Response 202
{
"started": true
}

List sandbox runs

GET /v1/vaults/:vaultId/sandboxes

Who can call itviewer

The workspace’s cloud sandbox tasks and triage runs, most recently started first, with the month’s sandbox hours. A run silent for 12 minutes, the sandbox’s 10-minute idle stop plus 2, and not started again in that time, reads as asleep; live counts only the running ones.

mux’s sandbox Worker records what it runs with PUT /v1/vaults/:vaultId/sandboxes/:id; who ran it is read from the credential, never the body.

Task status remains visible to workspace members. A task’s starter alone can read its conversation, attach its agent, access its files or run commands. Ownership is fixed when the task is admitted; another member’s key cannot take it over by reporting a new start or requesting a token. Browser view and chat tokens also require that owner. Shared knowledge belongs in the workspace memory repo.

Before a sandbox starts or wakes, the Worker asks POST /v1/vaults/:vaultId/sandboxes/:id/admit. Admission needs at least the agent role, so a viewer cannot start one, and a plan with no sandbox, such as Hobby, answers 402 plan_refused. Sandbox hours, sandboxes awake at once, Triage tokens and Clef are counted per person: in a team each member spends their own plan’s allowance, wherever they spend it. A team that pays for a plan of its own holds its members to that plan there, and its sandboxes awake are counted apart from each member’s own. Use is charged to whoever paid when it was used: when a team starts or stops paying for a plan of its own mid-month, what was already used stays where it was charged. A start past a cap answers 402 with the cap body below; sentence is what to show the reader, and nextPlan is the plan to offer, or null on Pro+.

Response 402
{
"error": "cap",
"meter": "sandboxHours",
"plan": "pro",
"nextPlan": "proplus",
"resetsAt": 1727740800000,
"sentence": "You've used this month's 40 sandbox-hours. Pro+ has 300 sandbox-hours and runs 12 sandboxes at once. Upgrade or wait for 1 October."
}

Query parameters

limit integer
1 to 100, default 50.
before string
The next cursor from the previous page.
include deleted
Include deleted runs.
kind task
Task runs only, leaving triage runs out.
mine 1
Only the runs the caller started. Needs a member behind the credential.
Request
curl "https://usemux.com/api/v1/vaults/01J9Z3K8QF/sandboxes?limit=1" \
-H "Authorization: Bearer $MUX_API_KEY"
Response 200
{
"sandboxes": [
{
"id": "3d0c1f7a-…",
"kind": "task",
"state": "asleep",
"startedBy": { "id": "usr_7Qb", "name": "Ada" },
"deviceName": "Ada's MacBook Pro",
"startedAt": 1727000000000,
"lastActiveAt": 1727003600000,
"endedAt": null,
"checkpoints": 2
}
],
"live": 0,
"next": "1727000000000.3d0c1f7a-…",
"usage": {
"hoursUsed": 3.2,
"hoursAllowed": 40,
"runningPerMember": 5,
"resetsAt": 1727740800000,
"warning": null
}
}

A Cowork task works a GitHub issue to a draft pull request on mux, with no Mac after its start. The Cowork guide says what it does; these are the routes behind it. Each answers one plain sentence when it refuses, as { "error": { "code", "message" } }. A start past a plan’s limit answers the cap body under Sandboxes.

Claim an issue

POST /v1/vaults/:vaultId/cowork/claim

Who can call itagent

Reads the issue and its repository through the mux GitHub App and records the task, so a second start of the same issue is refused. Answers the issue, the default branch, the commit and its tree, the author to use, and the commit’s guide and .muxcode/sandbox.json. mux’s sandbox Worker makes this call for POST /v1/cowork/tasks; a client calls that instead.

Body

taskId uuid required
The task’s id.
repository string required
owner/name.
number integer required
The issue.
kind bug | feature required
What the reader says the issue is.

Refusals include app_not_installed (with installUrl), repository_not_covered, github_access_required, app_permissions_missing and already_working, which names the pull request or task that holds the issue. A plan with no included model and an unreadable or empty issue are refused too, and so is a start commit a run could not finish: past about 4,000 tracked files (tree_too_large), with a submodule (submodules), or with a .gitattributes line that sets filter, ident, working-tree-encoding or eol=crlf (filter_attribute, rewriting_attribute; eol=crlf on Windows’ own scripts is let through). An included model’s allowance already spent answers 402 with a cap body, { error: "cap", meter: "model", resetsAt, sentence }.

Release a claim

POST /v1/vaults/:vaultId/cowork/release

Who can call itagent

Records why a claimed start never ran, and lets the issue be started again. Send taskId and reason.

Move a task to your current key

POST /v1/vaults/:vaultId/cowork/key

Who can call itagent

Moves a task’s GitHub token and Clef to the key this call comes with, as an admission of the task does, for its starter in person. Send taskId. Asking for a pull request again does this by itself, so signing out and back in does not end it.

List Cowork tasks

GET /v1/vaults/:vaultId/cowork/tasks

Who can call itagent

The caller’s own Cowork tasks, newest first: a task’s transcript and files belong to whoever started it. Each has its issue, base and commit, runStatus and runReason, its pull request as { state, branch, number, url, reason, retryable } where state is waiting, opening, opened, maybe_opened or refused, and whether it still holds the issue (standing). Add ?repository=owner/name to read one repository’s.

Read whether Cowork can start

GET /v1/vaults/:vaultId/cowork/readiness

Who can call itagent

What a Cowork page shows before anything is spent, for ?repository=owner/name: { plan, installed, covered, installUrl, base, commit }. With the included model’s allowance spent it answers as the claim would, 402 with the cap body.

Start a Cowork task

POST https://sandbox.usemux.com/v1/cowork/tasks

Who can call ita person's key

Picks the task’s id, claims the issue, admits the task as any sandbox and answers 202 { "task": "<uuid>" }, while the start goes on with no one attached. It counts against the same sandbox hours and awake-sandbox limit as any task. Past a cap it answers the cap body, and the claim is released.

Body

repository string required
owner/name.
number integer required
The issue.
kind bug | feature required
What the issue is.
project string
24 hex digits. Defaults to the first 24 of the digest of the lowercased repository.
homeBundle string
A cached home bundle’s digest.
skills string[]
Skills the run names.
identity object
{ name, email }: the commit’s author, in place of the account’s.
checks object
{ project, deep }: which checks the run makes.

Read a task's run

GET https://sandbox.usemux.com/v1/tasks/:id/workflow

Who can call ita task token with the agent scope

{ runs, judgements, cursor }: the task’s workflow run as its engine holds it, and its classifier readings, which a mirror keeps. Only the task’s starter reaches it.

Control a task's run

POST https://sandbox.usemux.com/v1/tasks/:id/workflow/control

Who can call ita task token with the agent scope

Send { runId, action, revision }, where action is pause, cancel, resume, reconcile, extend or synthesize; anything else answers 400. A run the month’s hours paused goes on from a resume once the hours return; until then it answers the cap body, and the task stays stopped. A revision that moved answers 409 and charges nothing.

Open a task's pull request

POST https://sandbox.usemux.com/v1/tasks/:id/cowork/pull-request

Who can call ita task token with the agent scope

Tries the pull request now, after a refusal or a try that did not land, and answers how it stands. Before the run completes it answers 409. It never opens a second: a try that lost its answer asks GitHub for the branch’s pull request first. It wakes a stopped task only when the commit is still to make, so the month’s hours refuse nothing else.

Two more routes serve a running task’s object and take only its meter ticket. POST /v1/sandbox-cowork/report records a task’s run status and pull request, a start it let go of (released), and when the allowance a paused run waits for returns (heldUntil). POST /v1/sandbox-github/token mints the App’s token for that task’s repository, read or write, and is not on the internet at all: mux’s sandbox Worker reaches it through a private service binding (API_GRANTS), since a meter ticket is what admission answers anyone with a key with. It never mints the workflows permission, so a Cowork pull request cannot change a repository’s CI. A start that was let go of gets no write token while another task works on its issue (409 issue_taken), so one issue gets one pull request. POST /v1/jev/systemone also takes a Cowork task’s meter ticket, charged to its starter exactly as their own key is.

A Mac signs itself in rather than holding a pasted key: it asks for a code, the person approves it in the browser, and the device collects a key of its own. muxcode does this for you; build it the same way for any client.

Start a device sign-in

POST /v1/connect

Who can call itnone; limited by address

Returns a code for the person to confirm at verificationUrl. Codes last ten minutes. The browser’s half is GET /v1/connect/requests/:userCode and its approve and deny, for a signed-in person.

Body

deviceName string required
What the person will see, up to 80 characters.
client string required
muxcode.
clientVersion string
Up to 40 characters.
deviceProof object
{ uuidHash, keychainToken? }: uuidHash is the SHA-256 hex of the Mac’s hardware UUID, hashed on the device; keychainToken is the token a trial’s first sign-in returned. A Mac that sends it may start a 72-hour trial of Pro, once per device, keychain, inbox and person, with a verified email address that is not disposable, unless the person already has Pro or Pro+, their own or on a seat a team pays for. One network starts at most five trials in 24 hours. A refused start names its reason: device, keychain, account, email or asn.
Request
curl https://usemux.com/api/v1/connect \
-H "Content-Type: application/json" \
-d '{ "deviceName": "Ada’s MacBook Pro", "client": "muxcode" }'
Response 201
{
"deviceCode": "q3V9…",
"userCode": "KQRT-7M2P",
"verificationUrl": "https://usemux.com/app/connect?code=KQRT-7M2P",
"expiresAt": 1727000600,
"interval": 3
}

Poll for the key

POST /v1/connect/poll

Who can call itthe device code

Poll at the returned interval until the person approves. The answer is a bare status: 202 pending, 429 slow_down when polled too soon, 410 denied, spent or expired. Once approved it carries the device’s own key; a code cannot be collected twice.

Beside the plan, the approved answer carries trial and meters. trial is null, or { startedAt, endsAt, jevMicroUsd, sandboxSeconds, outcome, reason? } with outcome one of live, ended, upgraded or refused; keychainToken is in it only on the answer that started the trial, or gave the Mac that started it a new one. Keep it in the keychain and send it back in deviceProof. meters is where the person stands against the caps they are held to; pooled is true in a team. meters.clefTokens holds the daily and five-hour Clef windows, in the shape POST /v1/jev/usage returns; past the plan’s cost line its blockedUntil is the month’s end, as the poll’s is. The jevMicroUsd fields are a legacy cost figure: never read token use from them.

A cap body refused during a trial names plan as trial.

A device signs itself out with DELETE /v1/connect/device. An owner or admin signs out any device with DELETE /v1/organizations/:orgId/devices/:keyId.

Body

deviceCode string required
From the start.
Request
curl https://usemux.com/api/v1/connect/poll \
-H "Content-Type: application/json" \
-d '{ "deviceCode": "q3V9…" }'
Response 200
{
"status": "approved",
"baseUrl": "https://usemux.com/api",
"organizationId": "org_2Yc81",
"corpusId": "01J9Z3K8QG",
"key": "hk_live_7QK2V9MZ4HXT…",
"workspaceName": "Acme",
"corpusName": "Code corpus",
"plan": "pro",
"role": "editor",
"trial": {
"startedAt": 1727000000000,
"endsAt": 1727259200000,
"keychainToken": "c2Vj…",
"jevMicroUsd": 0,
"sandboxSeconds": 0,
"outcome": "live"
},
"meters": {
"sandboxHoursUsed": 0,
"sandboxHoursCap": 3,
"sandboxesAwake": 0,
"sandboxesCap": 1,
"jevMicroUsdUsed": 0,
"jevMicroUsdCap": 2150000,
"clefTokens": {
"daily": { "used": 0, "reserved": 0, "limit": 280000, "remaining": 280000, "resetsAt": 1727049600000 },
"fiveHour": { "used": 0, "reserved": 0, "limit": 100000, "remaining": 100000, "resetsAt": 1727010000000 },
"observedAt": 1727000000000,
"blockedUntil": null
},
"resetsAt": 1727259200000,
"pooled": false
}
}

Start a trial from a signed-in Mac

POST /v1/connect/trial

Who can call itthe device's own key

A Mac already signed in asks for its trial without a second sign-in in the browser. Only a device’s key may ask, not one made by hand. The rules are the sign-in’s: once per device, keychain, inbox and person, and at most five starts per network in 24 hours. The answer is { plan, trial, meters } in the poll’s shapes; trial.keychainToken is in it only when this call started the trial or gave the Mac that started it a new one.

Body

deviceProof object required
{ uuidHash, keychainToken? }, as sent to POST /v1/connect.

Mint a key

POST /v1/vaults/:vaultId/keys

Who can call itowner, signed-in person

Mints a workspace key. The key is in this answer only. GET /keys lists the workspace’s keys, revoked ones included, and DELETE /keys/:id revokes one; both also need a signed-in owner.

Body

role string required
viewer, agent, editor or owner.
principalType string required
agent for a program, human for a person’s own tool.
agentName string
Required for an agent key: what it is, up to 100 characters.
expiresAt integer
When it stops working, in milliseconds. Keys do not expire by default. A time already past answers 400 validation_error.
Request
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/keys \
-H "Cookie: $SESSION_COOKIE" \
-H "Content-Type: application/json" \
-d '{ "role": "agent", "principalType": "agent", "agentName": "ci-bot" }'
Response 201
{
"id": "01J9Z4D1K8",
"key": "hk_live_R3D8WN6CJ0PE…",
"role": "agent",
"principalType": "agent",
"agentName": "ci-bot",
"expiresAt": null,
"createdAt": 1727000000000
}

Retrieve billing

GET /v1/billing

Who can call itany key or member

The organization’s plan, its limits and this month’s usage. trial is true while a live trial sets the allowances, and pooled is true in a team. meters is the caller’s own standing, in the device sign-in’s shape plus two fields: searchHoursUsed, the search and memory hours the payer used this calendar month, and searchHoursCap, the plan’s (0 on a plan with no search). teamOrganization, sent to a signed-in session and never to a key, is true when no person owns the organization: a team’s. teamPlanStopped is the plan Polar still bills for a team whose own plan stopped a day after a failed charge, and null unless the caller holds that team’s billing. GET /v1/billing/plan returns only {plan}. Changing a plan or the billing contact happens in the app, for the organization’s billing owner.

Request
curl https://usemux.com/api/v1/billing \
-H "Authorization: Bearer $MUX_API_KEY"
Response 200
{
"orgId": "org_2Yc81",
"plan": "pro",
"status": "active",
"currentPeriodEnds": 1729592000000,
"pendingPlan": null,
"pendingPlanAppliesAt": null,
"trial": false,
"pooled": false,
"meters": {
"sandboxHoursUsed": 3.2,
"sandboxHoursCap": 40,
"sandboxesAwake": 0,
"sandboxesCap": 5,
"jevMicroUsdUsed": 1080,
"jevMicroUsdCap": 2150000,
"clefTokens": { "daily": { "…": "…" }, "fiveHour": { "…": "…" }, "observedAt": 1727000000000, "blockedUntil": null },
"resetsAt": 1727740800000,
"pooled": false,
"searchHoursUsed": 4.5,
"searchHoursCap": 50
},
"billingReconciliationRequired": false,
"cancelAtPeriodEnd": false,
"hasBillingAccount": true,
"canManage": false,
"billingTransferTargets": [],
"limits": {
"vaults": 1,
"apiCallsPerMin": 120,
"apiCallsPerMonth": 500000,
"semantic": true,
"indexedRepositories": 20,
"indexRefresh": "push",
"sandboxesPerMember": 5,
"sandboxHoursPerMonth": 40
},
"usage": {
"vaults": 1,
"indexedRepositories": 2,
"apiCalls": 1234
},
"billingMode": "real",
"teamPlanStopped": null
}

Ask Clef

POST /v1/jev/systemone

Who can call ita person's key, a sandbox task token, or a Cowork task's meter ticket

Clef, the classifier, through mux. Send a JSON object with state, model and questions. A call runs Clef (@cf/cloudflare/clef) unless model is exactly clef-flash, which runs Clef Flash; clef, jev-latest and an empty name all run Clef. Input tokens of either model count against the allowance alike. A successful response contains model, answers and usage.

Pro and trials include 280,000 input tokens per UTC day and 100,000 per fixed five-hour window. Pro+ includes 2,800,000 and 1,000,000. Both limits apply to the person across all workspaces. Five-hour windows start at Unix epoch multiples of five hours and run independently of the daily reset.

Before inference, mux reserves an input-token bound in both windows. After inference, it replaces that reservation with the provider’s reported input tokens. The call runs to its end even if the client disconnects, so its reservation still settles. A reservation still unsettled 30 seconds after it was made counts as spent until its windows reset, and one still unsettled after an hour is charged at its reserved tokens.

A window is spent once less is open in it than the smallest reservation the person made there, capped at 1% of the window’s limit, or than 400 tokens, the smallest valid request. Open is the limit less used tokens and spent reservations. Media calls reserve the full 65,536-token context and set no floor.

Headers

Idempotency-Key string
Optional: 1 to 128 of A-Z, a-z, 0-9, ., _, : and -; anything else returns 400 validation_error. A key belongs to the person and organization, so the same key from another person or organization starts a separate call. A retry with the same key and body never reserves or runs Clef again. It gets the first call’s stored reply, status and body, errors included, even when the cost line would refuse a new call by then. A plan that no longer includes Clef refuses the retry with 402. While the first call still runs, the retry waits up to 30 seconds from that call’s reservation, then returns 504 jev_timeout. A request refused before reservation stores nothing, so its key is judged afresh. mux keeps a reply for 10 minutes. After that, a retry with the key may return 504 jev_timeout; it never runs Clef.

Refusals

402 cap spent
A window is spent. The cap body has meter: "jev" and clefTokens. Its resetsAt, like clefTokens.blockedUntil, is the latest reset needed to resume, and can come before used reaches limit. Hobby and an ended trial return 402 plan_refused.
422 jev_request_budget too large
This request cannot fit before a window resets, though a smaller one could. Clef stays on. The body carries clefTokens beside error.
429 jev_busy retry
The request fits once fresh calls, reserved under 30 seconds ago, settle. Retry shortly. The body carries clefTokens beside error.
422 idempotency_conflict Idempotency-Key
The key was sent before with a different body.
504 jev_timeout timeout
Clef took longer than 15 seconds, or a keyed retry’s first call left no reply in time.

Invalid input returns 400, and a body over 13 MiB returns 413, before reservation. Upstream errors retain the reservation when usage is uncertain. Missing or invalid usage returns 502 jev_usage_unavailable. If reported usage exceeds its reservation, the full usage stays counted and further calls are blocked until those windows reset. A failed cost-ledger write neither refunds tokens nor fails the call: the answer is still 200, and mux writes the row later. No Workers AI binding returns 503 jev_unconfigured before reservation.

Reuse an Idempotency-Key only after a timeout or a dropped connection. Send a new key after any HTTP reply, since a retry replays stored errors too.

Request
curl https://usemux.com/api/v1/jev/systemone \
-H "Authorization: Bearer $MUX_API_KEY" \
-H "Content-Type: application/json" \
-d @questions.json

Read Clef usage

POST /v1/jev/usage

Who can call ita person's key

Read the person’s included Clef usage. This route never charges usage: calls through systemone settle there, and BYOC calls use the person’s own Cloudflare account. Send inputBytes: 0; positive legacy reports are accepted but do not spend included tokens. The clefTokens object carries daily and fiveHour windows, each with used, reserved, limit, remaining and resetsAt. It also carries observedAt and blockedUntil. Both timestamps use epoch milliseconds. over and refusal describe actual token-cap exhaustion, never reserved tokens alone. Past the plan’s cost line, where every Clef call answers 402, the poll answers over: true with that refusal, and blockedUntil is the month’s end. Legacy dollar fields remain for older clients and internal cost reports; new clients use clefTokens.

Body

inputBytes integer required
Send 0 to read usage. Positive legacy values do not charge the allowance.
Response 200
{
"jevMicroUsdUsed": 1080,
"jevMicroUsdCap": 2150000,
"clefTokens": {
"daily": { "used": 12000, "reserved": 0, "limit": 280000, "remaining": 268000, "resetsAt": 1791244800000 },
"fiveHour": { "used": 12000, "reserved": 0, "limit": 100000, "remaining": 88000, "resetsAt": 1791234000000 },
"observedAt": 1791226800000,
"blockedUntil": null
},
"over": false,
"refusal": null
}

The web app manages workspaces, people, GitHub and billing through these routes; muxcode and the sandbox Worker use the last few. They need a signed-in person unless noted. A few routes muxcode calls for itself, such as its own plan, a workspace’s access and the included model, are not listed here.

Method Path Who Purpose
POST /v1/workspaces/default person Make the Personal workspace a new account starts with, when it holds none and has no invitation waiting; { vault }, or { vault: null } when none was due
POST /v1/workspaces person Create an organization and its first workspace
POST /v1/vaults org owner Create a workspace; body: name
PATCH /v1/vaults/:vaultId owner Rename a workspace
DELETE /v1/vaults/:vaultId owner Delete a workspace; kept for 30 days, then deleted with its code index and agent memory, every member’s personal memory included
POST /v1/vaults/:vaultId/restore org owner Restore a deleted workspace within 30 days
GET /v1/vaults/:vaultId/grants owner Who can reach the workspace; inTeam marks a team member’s grant on the team’s workspace
POST /v1/vaults/:vaultId/grants owner Grant a member access; body: email, role
DELETE /v1/vaults/:vaultId/grants/:principalId owner Revoke a grant; 409 team_member for a team member’s grant on the team’s workspace, which goes only when they leave the team
GET /v1/vaults/:vaultId/analytics viewer Home’s charts; days: 7, 30 or 90
GET /v1/organizations/:orgId/members member Members, pending invitations, signed-in Macs
POST /v1/organizations/:orgId/invitations owner or admin Invite a person; body: email, role
DELETE /v1/organizations/:orgId/invitations/:id owner or admin Cancel an invitation
DELETE /v1/organizations/:orgId/devices/:keyId member (own) or admin Sign a device out
GET /v1/organizations/:orgId/github org owner GitHub connection state
POST /v1/organizations/:orgId/github/install org owner Start the GitHub App installation, or link one with {"link":true}
POST /v1/organizations/:orgId/github org owner Finish the installation from GitHub’s callback
DELETE /v1/organizations/:orgId/github org owner Disconnect GitHub and drop its selections
POST /v1/billing/checkout billing owner Start a checkout; body: plan
GET /v1/billing/checkout/:checkoutId billing owner Confirm a checkout return
POST /v1/billing/change-plan billing owner Change a paid plan
POST /v1/billing/keep-plan billing owner Drop a scheduled plan change
POST /v1/billing/transfer-owner billing owner Hand billing to another member
POST /v1/billing/cancel billing owner Cancel at the period’s end
POST /v1/billing/reactivate billing owner Undo a pending cancellation
POST /v1/billing/portal billing owner Open the billing portal
POST /v1/billing/webhook Polar signature Billing events
POST /v1/webhooks/github-app GitHub signature Push and installation events; a push to an indexed branch marks it stale
GET /v1/vaults/:vaultId/month viewer The month so far, for Home: searches, sandbox and index hours, Triage runs
GET /v1/vaults/:vaultId/activity viewer What is under way now, for the activity tray
GET /v1/vaults/:vaultId/github/branches editor A granted repository’s branches; query: repository
GET /v1/vaults/:vaultId/sandboxes/:id viewer One sandbox run, for the task page
GET /v1/vaults/:vaultId/sandboxes/:id/owner the task’s owner Who owns a task
POST /v1/vaults/:vaultId/sandboxes/:id/token a key with the agent role, the task’s owner Mint a 10-minute task token
POST /v1/vaults/:vaultId/sandboxes/:id/view-token the task’s starter A view or chat token for the task page
POST /v1/sandbox-tokens/refresh a task token Refresh a task token
POST /v1/organizations/:orgId/sandbox-tokens/revoke owner or admin End every task token in the organization
POST /v1/sandbox-meter the sandbox’s meter ticket Meter readings from a running sandbox