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 CLI or Node SDK unless you specifically need raw HTTP control.

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

1. Register Agent Public Key
2. List Vaults
3. List Vault Items
4. Get Vault Field Value when you already know the fieldId
5. Get Vault Item Detail when you need the whole item's values

The first successful public-key registration is what makes the agent eligible for security-group, project, and direct vault access. Operators should grant those access paths only after step 1 succeeds.

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 checkpoint-signed vault metadata writes when the runtime has an active registered encryption key.

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 CLI, 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 require checkpoint-backed writes, 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 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 checkpointed vault attachments through the machine API.

Marketplace Endpoints

Search the catalog, manage machine-owned carts, and checkout orders.

Webhook Endpoints

Create outbound webhook subscriptions for scoped machine events.

Domain Manager Endpoints

Manage DNS records for domains purchased through R4.

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

Currently, endpoints return all results in a single response. Future endpoints may support pagination with the following format:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "totalPages": 3
  }
}

Query parameters for paginated endpoints:

Changelog

v1.10.0 (March 2026)

• Added GET /api/v1/machine/me for machine identity, context, and capability introspection
• Added POST /feedback for AGENT capability-gap feedback
• Added the Submit Feedback endpoint guide and linked it from the agent-facing docs

v1.9.0 (March 2026)

• Added links for the machine vault update, vault-item update, and vault-item move write paths
• Added the audited Machine Endpoint Inventory

v1.8.0 (March 2026)

• Added machine monitoring endpoints under /monitoring
• Added scoped metric-stats and entity-counts reads for machine observers
• Added global-admin-gated system-stats and session-stats for infrastructure monitoring

v1.7.0 (March 2026)

• Added machine agent lifecycle endpoints under /agent
• Added direct agent tenant-role reads/writes under /agent/:id/tenant-roles
• Added machine project/vault permission management under /permissions/:assetType/:id/*

v1.6.0 (March 2026)

• Added GET /vault/:vaultId/fields/:fieldId for narrow single-field reads with the parent signed detail checkpoint

v1.5.0 (March 2026)

• Removed the legacy GET /vault/env/:projectId plaintext env endpoint
• Added signed machine vault summary/detail checkpoint metadata to GET /vault/:vaultId/items and GET /vault/:vaultId/items/:itemId
• Tightened machine vault writes so create/archive flows now require user-backed signed checkpoints and client-encrypted field values

v1.3.0 (February 2026)

• Added POST /vault/:vaultId/items endpoint for creating vault items

v1.2.0 (January 2026)

• Added GET /project endpoint for listing all projects
• Added POST /project endpoint for creating projects

v1.1.0 (January 2026)

• Added GET /project/:id endpoint for project details

v1.0.0 (January 2026)

• Initial release
• Added GET /domain-manager/dns-records endpoint