API Reference

This page is the quick endpoint index for the machine API.

It sits between the conceptual docs and the full HTTP reference:

1. Machine API Overview explains the model, auth setup, and policy rules
2. this page gives you the fastest route to the right endpoint or endpoint guide
3. Detailed Machine API Reference covers full request and response details
4. Machine Endpoint Inventory is the audited controller-level route list

Use the Node SDK unless you specifically need raw HTTP control. The CLI manages local account and agent profiles that the SDK can also load.

If you are using R4 as a password manager for an agent runtime, follow this sequence first:

1. Create the agent in the Platform wizard and import the one-time JSON with CLI or Node SDK
2. List Vaults
3. List Vault Environment Fields for project env export
4. List Vault Items for broader item discovery
5. Get Vault Field Value when you already know the fieldId
6. Get Vault Item Detail when you need the whole item's values

The Platform wizard registers the initial runtime public key. Use Register or Rotate Agent Public Key for explicit rotation or repair workflows, not as a required step for every environment read.

Recommended Agent Flow

Rotating to a different runtime key still requires the current private key and, when the old key still has active vault access, a complete replacement wrapped-DEK batch.

Important Current Constraint

AGENT-scoped machine API keys are the supported runtime path for password retrieval, secret usage, and machine vault writes when their policy and asset access allow the operation.

Attachment parity, procurement flows, and outbound machine webhooks now live on the same machine API, but they still require the right endpoint permissions and any extra tenant or org roles. See Current Limitations.

Machine API keys can also be limited by policy. The simplest setup is machine.all, but least-privilege runtimes can choose grouped grants such as machine.vault.all or individual permissions such as machine.vault.read and machine.vault.secret.read.

If you are building a "master agent" that creates other agents, add machine.agent.all, machine.permissions.all, and the tenant role TENANT_AGENT_MANAGER.

Use Agent Orchestration and Permission Management when you are building delegated agent workflows instead of simple secret retrieval.

If you want machine-side metadata discovery without broad project/admin powers, add machine.search.read. Continuous runtimes that need full or delta sync should add machine.vault.sync.read or the grouped machine.vault.all.

If you are building a read-only observer or anomaly-detection runtime, add machine.monitoring.read. metric-stats, entity-counts, request-events, audit-events, and vault-activity-events are scoped to the authenticated machine session; system-stats and session-stats are reserved for global-admin-backed machine keys.

If the SDK, MCP server, or current raw machine API is missing a capability your AGENT runtime needs, submit product-gap feedback through POST /api/v1/machine/feedback.

Identity Endpoint

Inspect the current machine principal, scope, tenant binding, and write-path constraints.

Search Endpoints

Search machine-visible metadata without decrypting secret values.

Project Endpoints

Manage projects and their associated resources programmatically.

Agent Endpoints

Create and manage subordinate AGENT runtimes programmatically.

These routes require both the machine permission family (machine.agent.read / machine.agent.write) and the session tenant role TENANT_AGENT_MANAGER. See Agent Orchestration for the end-to-end lifecycle and delegation flow.

Feedback Endpoints

Report unsupported product capabilities from an AGENT runtime.

This route is AGENT-only and requires machine.feedback.write or machine.feedback.all. Do not send secrets, plaintext credentials, or private user data in the feedback body.

Permission Endpoints

Manage project, vault, or vault-item access entries through the machine API.

Project permission edits are the simplest delegated-access flow. Vault and vault-item permission edits reuse the same platform ACL graph, and vault items still inherit parent-vault access. See Permission Management for the full request body, helper endpoints, and orchestration order.

set-permissions replaces the full permission list. Include every entry you want to keep, including the caller's own ADMIN row.

Vault Endpoints

Access and manage vault items and secrets programmatically.

Vault metadata such as vault names, item names, field labels, and websites is not end-to-end encrypted. Only field values are end-to-end encrypted v3 vault envelopes.

For /vaults compatibility aliases, vault-group, vault-import, wrapped-key, user-key-pair, shared-item, and vaults-data routes, use the Machine Endpoint Inventory or the Detailed Machine API Reference.

Attachment Endpoints

Manage encrypted vault attachments through the machine API.

Pincer License Endpoints

Purchase and terminate licenses through the compact Pincer machine API. Catalog browsing, cart management, product detail, and catalog-admin provisioning routes are not public API surfaces.

Use the public license catalog to copy an API-available license slug for licenseId. For an existing vault destination, copy the vault ID from Platform > Vaults > vault row More actions > Copy vault ID.

Webhook Endpoints

Create outbound webhook subscriptions for scoped machine events.

Domain Manager Endpoints

Manage DNS records for domains purchased through R4.

Billing Endpoints

Read billing state and fund the workspace from machine credentials. See the Detailed Machine API Reference for payment-method and setup-intent routes.

GET /billing/distributor-charges accepts month (YYYY-MM), licenseInstanceId, tenantId, and includeLines=true for per-day line detail. It powers r4 licenses charges in the CLI.

Budget Endpoints

Inspect or create governed subject budgets through the machine billing surface.

Monitoring Endpoints

Read machine-visible monitoring data and platform health summaries.

Common Response Formats

Success Responses

All successful responses return JSON with a 2xx status code. The response body structure varies by endpoint.

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message"
  }
}

Common error codes:

Pagination

List endpoints accept optional page and limit query parameters. When page is omitted, the endpoint returns all results with no pagination metadata, which keeps older integrations working unchanged.

When page is supplied, the response includes a meta object alongside the endpoint's list key (agents, apiKeys, users, data, and so on):

{
  "agents": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 25,
    "totalPages": 6
  }
}

Paginated list endpoints include agents, tenant/org API keys, tenant users and invitations, integrations, intelligence providers, crypto funding intents, credit transactions, domain tenants, and security groups. Endpoints that do not take page/limit (for example GET /vault and GET /vault/:vaultId/items) always return the full scoped result set.

Changelog

The canonical machine API changelog lives in the Detailed Machine API Reference. This quick index no longer keeps a separate version history, because the two changelogs had drifted apart.