API reference

Every endpoint documented here is part of the supported public contract and carries a compatibility promise. Fields may be added to requests and responses; they will not be removed or repurposed, and operation identifiers are frozen so generated clients keep compiling.

Do not depend on an endpoint just because you observed the product calling it. Undocumented routes can change or disappear without notice. If you need something that is not here, ask before depending on it.

Base URL and versioning

https://api.guestmachines.com

The version lives in the path, and the current version is v1. A breaking change would appear as a new version rather than as a change to this one.

What the contract covers

The supported surfaces are enough to authenticate clients, discover capabilities, manage connectors, run work, and observe it:

Delegated tokens can provision and update user-owned agents, teams, pipelines, and MCP connectors. A delegated application representing a current organization admin or owner can also manage the connector library with an explicit publish grant. Team membership changes use one atomic full-set replacement. Agent/team/pipeline deletion, agent revision restore, webhook destination management, budgets, and policies remain deliberately absent; use the console for those operations.

The Runs section also exposes the complete public file handoff: upload raw bytes as a ready artifact, attach its returned ID through artifact_inputs, list visible artifacts and run bindings, and create short-lived download or preview URLs. Only the routes listed in this reference are supported for integrations.

Credentials

Integrations use one of two reusable bearer credentials:

Service-principal keys and delegated tokens are each bound to one organization and need no X-Org-Id header. Authentication covers how to choose between them.

The Authentication section also documents a UserSession scheme for the human-only operations where an admin registers a delegated client and a member reviews, grants, or withdraws consent. This is a short-lived browser credential, not something an integration should capture or store. Only a direct user session can use X-Org-Id to select among the user's active memberships.

What a run without a user identity can do

Every execution endpoint — single agent, team, and pipeline — accepts either credential. A run started with a service-principal key simply has no acting user: it is attributed to the key, and anything user-scoped resolves to the relevant agent's owner instead. Agent memory and prompt context work normally.

Two tools have no such fallback, because they need a specific human rather than a lane to write into:

If an agent, team member, or pipeline step depends on either, start the run with a delegated token so it has a user behind it.

Each endpoint states which credentials drive it.

Scopes

A service principal or delegated token carries scopes of the form resource:action. The scopes this contract uses:

Grant the narrowest set that works. A wildcard action such as agents:* is accepted and includes destructive actions. MCP publication is always separate: mcp_servers:* does not include mcp_servers:publish.

Configuration writes need the right identity

Creating a saved configuration needs a user owner, so agent, team, pipeline, and MCP connector create operations accept a delegated token but not a service-principal key. The new resource belongs to the represented user. Creating an MCP connector directly in the organization library additionally requires mcp_servers:publish and a current admin or owner role.

Updates follow the existing resource rules. A delegated token can update only its user's resources. A service principal can update an organization-shared agent or pipeline when its edit scope and optional resource allowlist cover the target; teams are organization-visible and follow the corresponding teams:edit rule. A service principal cannot attach a user's private connector while editing a shared agent. Organization-library connectors remain attachable.

Pipeline create and update also authorize every effective step and fallback. Grant agents:invoke and/or teams:invoke for the target types used by that pipeline, even for a metadata-only update: the complete saved graph is checked again before the write succeeds.

Scopes are not sufficient on their own

Visibility is evaluated before scopes. A service principal can never reach a resource whose visibility is private, whatever it holds. Agents, pipelines, and chats are private when created, so a new automation account typically sees nothing until you share the resource with the organization or grant the principal explicit access to it.

The practical consequence is that list endpoints omit what the caller cannot see rather than failing. An empty list means one of three things — the workspace is empty, the scope is missing, or every match is still private — and only the second produces an error anywhere.

Conventions

Identifiers are UUIDs, except runs, which are integers.

Collections accept limit (1–100, default 50) and offset, and return a total alongside the page. The total counts what the caller can see, not what exists.

Timestamps are ISO 8601 in UTC.

Every response carries X-Request-Id. Log it and include it when reporting a problem; error bodies repeat it.

Execution is asynchronous

Starting an agent answers 202 with a run, not with a result. The request is validated before it is accepted, so limit, budget, and authorization errors are returned immediately. Poll run progress for its current state, or subscribe to the event stream for live lifecycle events.

Answer human interactions

A run can stop at awaiting_user_input when ask_user needs typed answers, or at awaiting_tool_approval before a governed tool call. These pauses survive reconnects and service restarts.

Start interactive work with a delegated token. When the run status or a webhook reports a pause:

1. Retrieve the pending interaction with runs:read.
2. Render the returned user_input questions or tool_approval action. Tool arguments are bounded and redacted, but they should still be treated as untrusted display content.
3. Answer that interaction with runs:edit, returning its opaque interaction_id unchanged.
4. Continue observing the run. A 202 means the decision was accepted; resume_status reports whether the run resumed.

For user input, selected carries the option's zero-based suggestion_index, while custom carries a value and is accepted only when the question sets allow_other. skipped uses the question's recommended suggestion and carries neither; a question that offers no suggestions has no recommended default, so it must be answered with custom and cannot be skipped or omitted. A high-risk tool approval includes confirm_label; an approval must copy that exact text into confirmation. A denial does not require it and may include denial_reason.

Treat 409 as a stale interaction: retrieve and review the current request instead of resubmitting the old decision. If a 202 returns resume_status=failed, the answer remains committed and the ordinary resume operation can retry resuming without changing the accepted decision. Generic resume cannot supply or bypass a pending answer.

Both operations require the same user who started the run. That user's delegated token can drive them; a service principal cannot, and an organization admin cannot answer another user's run. Live mid-run steering is not part of the public API.

Govern plan decisions

When a run reports awaiting_plan_approval or paused_for_replan, retrieve its active plan before deciding. You can approve or deny that plan with runs:edit. Approval attempts to resume the run; denial leaves it paused.

Replacing a plan is narrower. Copy the two values from replan_fence into the request, and treat 409 as a signal to read and review the newer plan. You may replace the complete tool selection, but cannot submit a natural-language team or timeline rewrite.

Only the user who started the run can replan it, using their session or delegated token. A service principal can read, approve, and deny organization runs when scoped, but it cannot replace a plan.

Idempotency

Execution starts accept an Idempotency-Key header, and artifact uploads require one. Generate one stable value per intended operation and reuse it only to retry that exact operation.

The key is scoped to the caller and target context, so two integrations cannot adopt each other's runs or uploads through a shared value. A replay must present the original payload or upload fingerprint: reusing a key with different input answers 409 rather than creating a second resource.

Retries are worth designing for on team runs in particular, where the default await mode holds the connection for the whole execution and invites gateway timeouts.

Rate limits

Expensive operations — starting agent, team, and pipeline runs — are throttled per service principal, on top of the organization's own concurrency, daily-run, token, and budget limits.

A 429 carries Retry-After when the limit has a known window. Concurrency limits always set it; daily caps and budget stops usually do not, because they clear at midnight UTC or need an operator to act. A 503 with rate_limiter_unavailable means the limiter itself is degraded and the request was refused rather than waved through; back off and retry.

Errors and retries covers which failures are worth retrying.

Compatibility

Within v1, we may add endpoints, add optional request fields, add response fields, and add new values to enumerations. Treat unknown response fields and unknown enum values as data to ignore rather than as errors, or an additive change will break your client.

We will not remove a documented field, change its type, change an operation identifier, or narrow an existing response. Anything that would require you to edit code arrives as a new version.

Endpoints outside this reference carry none of the above.