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.
Authentication
Section titled “Authentication”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.
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/workspace \ -H "Authorization: Bearer $MUX_API_KEY"Errors
Section titled “Errors”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_jsonwhen 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_gatewhen the route needs a signed-in person.plan_refusedandplan_limitwhen the plan does not include it.404 not_found- no such thing, or one your credential cannot see. A workspace in another organization answers404, never403, so a key cannot learn what exists elsewhere.409- the request conflicts with the workspace’s state, such asno_repositories,refresh_in_progressorteam_member.422- the request is well formed but cannot be done:jev_request_budgetwhen a Clef call cannot fit before its window resets,idempotency_conflictwhen anIdempotency-Keycomes back with another body,invalid_memberwhen a grant names someone outside the organization.429- a rate limit; see below. Clef also answers429 jev_busywhile calls still pending hold the room a new one needs. Code search and memory answer429 search_hours_spentpast the month’s search and memory hours, andget_context429 context_rate_limitedpast 60 calls an hour.5xx- mux or a service behind it did not answer.503 index_unavailableis safe to retry.
{ "error": { "code": "not_found", "message": "Vault not found." }}Rate limits
Section titled “Rate limits”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-RemainingandX-RateLimit-Reset(Unix seconds) for the burst bucket.X-Quota-LimitandX-Quota-Remainingfor 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.
HTTP/1.1 429 Too Many RequestsRetry-After: 12X-RateLimit-Limit: 120X-RateLimit-Remaining: 0X-RateLimit-Reset: 1727000060{ "error": "Rate limit exceeded", "scope": "burst", "retryAfter": 12}Workspaces
Section titled “Workspaces”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
-
planstring free(Hobby),pro,proplus,ultraorteam.-
rolestring - The caller’s role in this workspace.
-
trialobject | null - The caller’s trial, in the device sign-in’s shape but never with a
keychainToken;nullwhen they have none. -
metersobject - Where the caller stands against their caps, in the device sign-in’s shape.
-
paymentobject | 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 untilstopsAt, a day after the failure, andplanreadsfreefrom then on.nullwhen nothing is owed, or when a key rather than a person is asking. -
capabilitiesobject semantic,structuralSearchandrepositoryFilters.semanticis false on Hobby.-
indexobject - The number of repositories indexed, file and chunk counts,
lastSuccessAtin milliseconds, and theembeddingVersionthe index was built with. -
managementUrlstring - Where the workspace is managed in the app.
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/workspace \ -H "Authorization: Bearer $MUX_API_KEY"{ "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
-
deleted1 - Signed-in person only: list the deleted workspaces you own instead. Each can be restored for 30 days with
POST /v1/vaults/:vaultId/restore.
curl https://usemux.com/api/v1/vaults \ -H "Authorization: Bearer $MUX_API_KEY"[ { "id": "01J9Z3K8QF", "orgId": "org_2Yc81", "name": "Acme", "slug": "acme", "createdAt": 1726500000000 }]Code search
Section titled “Code search”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
-
organizationIdstring required - The organization the workspace belongs to. Any other answers
404 not_found. -
operationstring required - One of
corpus_status,list_repositories,grep_code,search_code,ask_code,get_contextortrace_code. -
argumentsobject - The operation’s arguments; see Operations below.
-
recordboolean falsekeeps the search out of the workspace’s analytics. Defaults totrue.
Operations
-
corpus_statusno 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 readsteamfor every member, andsearchis what decides. Read from stored state; it never wakes the index. -
list_repositoriesno arguments {repositories}, each with itsnameand indexedheadSha.-
grep_codepattern · 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_codequery · limit, repository, language, path - Results ranked by meaning, so a search can find code that never uses its words. A
pathkeeps one file or folder: insiderepositorywhen you name one, and otherwise starting with the repository, asowner/name/src. A path that names no repository is refused with400. Pro, Pro+ and a trial. -
ask_codequery - The passages that bear on a question, as
grounding. It does not write the answer:answerisnull, and your model reads the passages. Pro, Pro+ and a trial. -
trace_coderepository, path · symbol, limit - One file on the code graph: what it
defines,imports, isimportedBy, itstestsand what it istestedBy, the routes it calls and is called from, and itsowners. -
get_contexttask · 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_refusedHobby - Every operation but
corpus_status: “Code search is included with Pro and Pro+, and during a trial.” -
429 search_hours_spentmonth - 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_limitedRetry-After get_contextpast 60 calls an hour for the workspace. The index is not woken. Retry afterRetry-Afterseconds.-
409 no_repositoriesnothing chosen grep_code,search_codeandask_codebefore any repository is chosen.corpus_statusandlist_repositoriesstill answer200.-
503 index_unavailableretry - The index did not answer, or is waking from rest. Retry;
corpus_statuskeeps answering. -
503 graph_unavailabletrace_code - The index has not written its code graph at the current commit yet. Refresh, then retry.
-
503 index_warmingget_context - The index is starting after a rest. Retry after
retryAfterSeconds, also sent asRetry-After. Anallow_staleretry can meet it too.
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 } }'{ "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…" } ]}{ "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
-
operationstring required status,list,read,search,write,append, orhistory.-
scopestring personal(default) orworkspace. No owner or member ID is accepted.-
argumentsobject readtakes a relativepath(defaultMEMORY.md) and optional historicalrevision.listtakes 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).searchtakesqueryand a limit up to 50.historytakes an optional path and limit up to 50.-
arguments for editsobject writeandappendrequirepath,content,revision(the last observed repo head, or null for a new repo), a UUIDmutationId, and asourcesession 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
-
taskstring required - The task, in words. Up to 4,000 characters.
-
repositoriesstring[] - Up to 20
owner/nameto 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 namesplan_limit_narrowedinomissions. -
revisionsobject[] - Pin a repository to a commit:
{repository, revision}. -
changedPathsobject[] - Up to 20
{repository, path}your change touches; they are read first. -
tokenBudgetinteger - From 1,024 to 16,000, default 6,000. Counted as UTF-8 bytes, an upper bound for byte-based tokenizers.
-
freshnessstring require_current(default) answers409 context_stalewhen an index is behind its branch, with thefreshnesslist and your plan’srefresh:push,nightly, ornonewhen the index refreshes only when asked. When a refresh is known to be pending or failed, the refusal comes without waking the index.allow_staleanswers from the indexed commit and namesstale_or_missing_sourcesinomissions.
Returns
-
evidenceobject[] - Each with
repository,path,line,endLine,headSha,excerpt,score, the file’s gitblob, and areason:literal,semantic,hybrid,changed-pathorgraph:<edge>. -
relationshipsobject[] - Code-graph edges between files in the packet -
imports,tests,calls_route- eachconfidence: "candidate", withtargetRepositoryandtargetRevisionwhen an edge crosses repositories. -
memoriesobject[] - Approved findings that still hold at these commits.
-
agentMemoryobject[] - Relevant shared workspace notes and the caller’s private notes. Each entry identifies
scope,revision,indexedRevision, anentrypointand rankedevidence, withauthority: "agent-authored". Memory uses at most a third of the packet budget. It is also available before a code repository is selected. -
omissionsstring[] - 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 memorymemory_entrypoint_truncated,memory_index_warming,memory_index_busy,memory_search_unavailableandmemory_unavailable. -
freshnessobject[] - Per repository: the expected and indexed revision, and
current,stale,missingorunknown.
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 } }'{ "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
-
receiptIdstring required - Your own receipt, unexpired.
-
repositorystring required owner/name.-
revisionstring required - A
headShafrom that receipt. -
statementstring required - The finding, up to 2,000 characters.
-
scopestring personalorworkspace.-
retentionDaysinteger - 1 to 30, default 7.
-
pathsstring[] - 1 to 20 files the receipt read that the finding rests on. Defaults to every file it read there.
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"] }'{ "id": "01J9Z4B2M1", "status": "proposed"}Repositories
Section titled “Repositories”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
-
statusstring mirroring,refreshing,fresh,staleorfailed.-
indexedShastring | null - The commit the index was built from.
latestShais the branch’s newest, andstaleis true when they differ. -
files, chunksinteger - What the index holds for it.
-
errorstring | null - Why the last index failed, in words.
-
waitingboolean failedonly because another index run held the index; the next run starts it.-
planLockedboolean failedonly 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.
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/repositories \ -H "Authorization: Bearer $MUX_API_KEY"{ "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
-
repositoriesobject[] required - Each
{repository, branch}.branchdefaults to the repository’s default branch.
Refusals
-
404 repository_not_grantedGitHub - The installation does not grant that repository.
-
403 plan_limitplan - 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
meterowned_repositorieswhen the total is yours, orowner_repositorieswhen it is this workspace’s owner’s, and the plan’slimit. -
409 github_not_connectedGitHub - Connect GitHub first.
-
409 selection_changedrace - 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.
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" } ] }'{ "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.
curl https://usemux.com/api/v1/vaults/01J9Z3K8QF/github/repositories \ -H "Authorization: Bearer $MUX_API_KEY"{ "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
-
repositorystring owner/name. Omit it to refresh everything.
Refusals
-
403 plan_refusedHobby - “Code search is included with Pro and Pro+, and during a trial.”
-
409 refresh_in_progressbusy - A refresh is already running.
-
429 rate_limitedRetry-After: 60 - A refresh was asked for less than a minute ago.
-
429 index_hours_spentRetry-After: month end - The workspace has used its index hours for the month. The nightly refresh still brings it up to date.
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" }'{ "started": true}Sandboxes
Section titled “Sandboxes”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+.
{ "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
-
limitinteger - 1 to 100, default 50.
-
beforestring - The
nextcursor from the previous page. -
includedeleted - Include deleted runs.
-
kindtask - Task runs only, leaving triage runs out.
-
mine1 - Only the runs the caller started. Needs a member behind the credential.
curl "https://usemux.com/api/v1/vaults/01J9Z3K8QF/sandboxes?limit=1" \ -H "Authorization: Bearer $MUX_API_KEY"{ "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 }}Cowork
Section titled “Cowork”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
-
taskIduuid required - The task’s id.
-
repositorystring required owner/name.-
numberinteger required - The issue.
-
kindbug | 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
-
repositorystring required owner/name.-
numberinteger required - The issue.
-
kindbug | feature required - What the issue is.
-
projectstring - 24 hex digits. Defaults to the first 24 of the digest of the lowercased repository.
-
homeBundlestring - A cached home bundle’s digest.
-
skillsstring[] - Skills the run names.
-
identityobject { name, email }: the commit’s author, in place of the account’s.-
checksobject { 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.
Device sign-in
Section titled “Device sign-in”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
-
deviceNamestring required - What the person will see, up to 80 characters.
-
clientstring required muxcode.-
clientVersionstring - Up to 40 characters.
-
deviceProofobject { uuidHash, keychainToken? }:uuidHashis the SHA-256 hex of the Mac’s hardware UUID, hashed on the device;keychainTokenis 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 itsreason:device,keychain,account,emailorasn.
curl https://usemux.com/api/v1/connect \ -H "Content-Type: application/json" \ -d '{ "deviceName": "Ada’s MacBook Pro", "client": "muxcode" }'{ "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
-
deviceCodestring required - From the start.
curl https://usemux.com/api/v1/connect/poll \ -H "Content-Type: application/json" \ -d '{ "deviceCode": "q3V9…" }'{ "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
-
deviceProofobject required { uuidHash, keychainToken? }, as sent toPOST /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
-
rolestring required viewer,agent,editororowner.-
principalTypestring required agentfor a program,humanfor a person’s own tool.-
agentNamestring - Required for an agent key: what it is, up to 100 characters.
-
expiresAtinteger - When it stops working, in milliseconds. Keys do not expire by default. A time already past answers
400 validation_error.
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" }'{ "id": "01J9Z4D1K8", "key": "hk_live_R3D8WN6CJ0PE…", "role": "agent", "principalType": "agent", "agentName": "ci-bot", "expiresAt": null, "createdAt": 1727000000000}Billing
Section titled “Billing”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.
curl https://usemux.com/api/v1/billing \ -H "Authorization: Bearer $MUX_API_KEY"{ "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-Keystring - Optional: 1 to 128 of
A-Z,a-z,0-9,.,_,:and-; anything else returns400 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 with402. While the first call still runs, the retry waits up to 30 seconds from that call’s reservation, then returns504 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 return504 jev_timeout; it never runs Clef.
Refusals
-
402 capspent - A window is spent. The cap body has
meter: "jev"andclefTokens. ItsresetsAt, likeclefTokens.blockedUntil, is the latest reset needed to resume, and can come beforeusedreacheslimit. Hobby and an ended trial return402 plan_refused. -
422 jev_request_budgettoo large - This request cannot fit before a window resets, though a smaller one could. Clef stays on. The body carries
clefTokensbesideerror. -
429 jev_busyretry - The request fits once fresh calls, reserved under 30 seconds ago, settle. Retry shortly. The body carries
clefTokensbesideerror. -
422 idempotency_conflictIdempotency-Key - The key was sent before with a different body.
-
504 jev_timeouttimeout - 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.
curl https://usemux.com/api/v1/jev/systemone \ -H "Authorization: Bearer $MUX_API_KEY" \ -H "Content-Type: application/json" \ -d @questions.jsonRead 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
-
inputBytesinteger required - Send
0to read usage. Positive legacy values do not charge the allowance.
{ "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}Routes for the app
Section titled “Routes for the app”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 |