API reference
The supported HTTP contract for Guest Machines integrations.
Every endpoint documented here is explicitly allowlisted 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.
Guest Machines also has a larger internal application API. An endpoint is not part of this contract because you observed the product calling it, and an undocumented route can change or disappear in any deploy. If you need something that is not here, ask before depending on it.
Base URL and versioning
https://api.guestmachines.comThe 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
Five surfaces, which together are enough to run work and observe it:
| Section | What it does |
|---|---|
| Agents | Discover agents, invoke one, list its runs |
| Teams | Discover teams and start governed workforce runs |
| Pipelines | Discover pipelines, run them, inspect step-level results |
| Runs | Observe, stream, cancel, and resume execution; retrieve artifacts |
| Triggers | Start configured work from an external system |
Provisioning and administration are deliberately absent. Creating agents, editing pipelines, managing members, configuring webhooks, budgets, and policies are console operations performed by a person with a role, not by a key. They are not published as an API because the authorization model does not make them available to one — see the credential rules below.
Credentials
Requests carry a bearer token. Two kinds reach this API:
| Credential | Prefix | Identity |
|---|---|---|
| Service principal key | gsmc_sk_ | The organization itself. No user. |
| Delegated token | gsmc_dt_ | A specific user, through an external application. |
Service-principal keys are already bound to one organization and need no X-Org-Id header. Authentication covers how to choose between them.
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:
| Tool | Behaviour with a service-principal key |
|---|---|
ask_user | Returns a tool error — there is nobody to ask. The agent decides on its own or fails with a reason. |
send_email | Returns a tool error — sending needs a verified sender identity. |
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:
| Scope | Grants |
|---|---|
agents:read | Read agents and their runs |
agents:invoke | Run an agent |
teams:list | Enumerate teams |
teams:read | Read a team and its workforce runs |
teams:invoke | Start a workforce run |
pipelines:read | Read pipelines and their runs |
pipelines:invoke | Run a pipeline |
runs:list | Enumerate runs |
runs:read | Read a run, its conversation, and its artifacts |
runs:edit | Cancel or resume a run |
Grant the narrowest set that works. A wildcard action (agents:*) is accepted but grants delete alongside everything else.
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; it is the correlation identifier to quote when reporting a problem, and error bodies repeat it.
Execution is asynchronous
Starting an agent answers 202 with the admitted run, not with a result. Admission is synchronous, so limit, budget, and authorization rejections surface on that call with their own status codes — a 202 means the run was authorized and affordable. Progress and outcome arrive by polling the run or subscribing to its event stream.
Idempotency
Execution starts accept an Idempotency-Key header. Generate one stable value per intended execution and reuse it only to retry that same execution.
The key is scoped to the caller and the target resource, so two integrations cannot adopt each other's runs through a shared value. A replay must present the original payload: reusing a key with different input answers 409 rather than starting a second run.
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.