Deployments.ai Docs

API overview

Base URLs, authentication, request conventions, and how the API reference is organized.

The Deployments.ai API is a JSON-over-HTTPS API under the /v1 path. Every capability on the platform is an operation in one OpenAPI 3.1 document. The TypeScript SDK is generated from that document, and the CLI is tested to cover every operation in it, so each operation has one SDK function and at least one CLI command.

Base URL

Send requests to your install's API origin. These docs write it as the placeholder https://api.example.com; Hosts and environments explains where your install's origin comes from. Shell examples in these docs read it from DEPLOYMENTS_API_URL.

curl "$DEPLOYMENTS_API_URL/health"

The health check needs no credential and returns {"status":"ok","service":"deployments-ai-api"}. Reading a thread stream is the one operation served from another origin. Use the streamUrl the API returns. Hosts and environments lists every origin.

Fetch the live contract from GET /v1/openapi.json, or run:

deployments openapi --json

Authenticate every request

Send a bearer credential in the Authorization header. A person uses a platform access token from sign-in. A service uses an API key that starts with dpl_. Most operations also need tenant headers that select the organization, project, or environment.

curl "$DEPLOYMENTS_API_URL/v1/agent-deployments" \
  --header "authorization: Bearer $DEPLOYMENTS_API_KEY" \
  --header "x-deployments-environment: $ENV_ID"

Authentication explains the schemes, the device sign-in flow, and the tenant header rules.

Request conventions

ConventionRule
BodiesRequest and response bodies are JSON. A few operations stream bytes or Server-Sent Events, and their pages say so.
IDsResource IDs are 26-character ULIDs in canonical uppercase Crockford base32.
TimestampsTimestamps are UTC with millisecond precision, for example 2026-10-01T12:00:00.000Z.
Tenant headersx-deployments-organization, x-deployments-project, and x-deployments-environment select the tenant.
IdempotencyMost mutations take an idempotency-key header. See Idempotency.
ListsLists use cursor and limit query parameters and return nextCursor. See Pagination.
Optimistic concurrencyUpdates to versioned resources, such as agent definitions and deployments, take the expectedVersion you last read. A stale version fails with status 409 and code version_conflict.

Response conventions

Successful responses return 200, 201, or 202. Each operation's page lists which one. A 202 means the platform accepted work that continues after the response, such as a run.

Failed responses use the problem details format with the application/problem+json media type. Problem responses carry an x-request-id header and repeat it in the body as requestId. Runtime, artifact, automation, and workflow execution operations are the exception. Their problem body includes requestId only when your request sent an x-request-id header. Errors describes the format and common codes.

How the reference is organized

Operations are grouped by tag. Each operation page shows the method and path, the security schemes, the headers and parameters, the request and response schemas, every error status, and SDK and CLI samples.

TagCoversStart with
TenancyOrganizations, standing, spend, limits, members, invitations, projects, environments, workspaces, service accounts, and API keysList organizations
SecurityDevice sign-in, identity, login domains, identity providers, directory sync, and the credential inventoryShow the authenticated identity
AppsAgent-built apps, member grants, releases, publication, and custom domainsList apps
AgentsAgent definitions, releases, deployments, and canariesList agent definitions
RuntimeThreads, messages, runs, approvals, tool calls, channels, webhooks, previews, and streamsSubmit an agent run
AutomationsSchedules and heartbeatsList schedules
ArtifactsRun and thread artifactsList artifacts
WorkflowsWorkflow definitions, releases, and executionsList workflow definitions
Managed SkillsSkill sources, releases, and installationsList skill sources
ToolsTool catalog and tool policiesList tool policies
ExtensionsMCP servers, MCP connections, extensions, and hosted codeList MCP servers
ProvidersProviders, OAuth apps, credentials, connections, and grantsList providers
ModelsModel catalog and model policiesList models
MemoryMemory spaces, grants, policies, search, and recallList memory spaces
BrainsOrganization knowledge, sources, documents, search, and askSearch Brains
Agent EmailAgent inboxes, messages, drafts, and domainsList inboxes
EmailSend-only email tenants, domains, and messagesCreate an email tenant
EvaluationsScore definitions, datasets, evaluation runs, and release comparisonsList score definitions
ObservabilityTraces, spans, metrics, and exportsList traces
OperationsUsage, cost, spend, API key usage, and audit eventsList usage records
BudgetsSpend budgets and budget periodsList budgets
GovernanceRetention, data export, erasure, and audit exportGet the retention policy
SystemHealth, install operator reads, organization standing and spend, and principal statusCheck API health

The SDK function index lists every function by the same tags.

Next

On this page