Deployments.ai Docs
Getting started

Core concepts

The resource hierarchy, the path from definition to release to deployment to run, principals, and scopes.

This page explains the handful of resources that every other page builds on. Read it once before you design how your product uses the platform.

Resources live in a four-level hierarchy

organization
└── project
    └── environment
        ├── workspace (optional)
        ├── service accounts and API keys
        ├── provider connections and credentials
        └── agent definitions, releases, and deployments
            └── threads
                └── runs
LevelWhat it is
OrganizationThe membership boundary. People join an organization with a role.
ProjectA group of environments for one product or integration.
EnvironmentThe isolation boundary for credentials, deployments, provider connections, and usage.
WorkspaceAn optional scope inside an environment. Threads, runs, and some definitions can carry a workspace ID.

Every resource ID is a 26-character ULID in canonical uppercase Crockford base32. Each level keeps its own status. An archived project accepts no new environments, and an archived environment accepts no new service accounts or API keys. Organizations, projects, and environments covers the lifecycle.

An agent moves from definition to run

The platform separates what you are editing from what is running.

ResourceMutable?What it holds
Agent definitionYesA draft AgentManifestV1 and a version counter that changes on every update and release.
Agent releaseNoA frozen copy of the manifest, a sha256: content hash, and a releaseNumber that counts up from 1.
Agent deploymentYesThe release that serves traffic in one environment, its desired and current state, and its runtime config.
ThreadYesOne conversation with one deployment.
RunNo*One execution of the agent on a thread, pinned to the deployment and release that ran it.

*A run's status changes as it executes, but its pinned deployment and release never change.

A deployment's desiredState is running, paused, or stopped. Its currentState is deploying, ready, paused, failed, or stopped. You can retarget a deployment to another release of the same definition, roll it back, or send a share of new threads to a candidate release as a canary. A stopped deployment cannot be resumed. Agents, releases, and deployments explains each operation.

A run's status is one of queued, running, waiting-for-approval, waiting-for-tool, completed, failed, or canceled. Runs start from the API, chat, email, schedules, heartbeats, webhooks, and workflows, and all of them use the same thread and run model. Threads and runs covers the runtime.

Principals act on resources

A principal is anyone or anything that calls the API.

  • Human principals sign in through the platform's identity service. They belong to organizations through memberships, and each membership has one role.
  • Service accounts are machine principals. Each one belongs to exactly one environment and authenticates with API keys. Service accounts and API keys describes them.
  • Platform administrators are human principals with the administrator platform role. They inspect and operate the install itself through the /v1/system operations. No organization role grants this.

Scopes and roles decide what a principal may do

Two checks decide what a request may do.

Capability scopes. Operations require a scope in the form namespace:level, such as agents:read or runs:write. A credential carries a list of scopes. A wildcard such as agents:* covers every level in that namespace.

Organization roles. For human callers, the API also checks live membership in the organization on every request. The role then narrows the token's scopes.

RoleAdds on top of reading
ownerEverything an admin can do, plus renaming the organization, managing owners, and requesting tenant erasure.
adminChanging projects, environments, workspaces, service accounts, API keys, agents, runs, memory, and connections. Managing non-owner members and invitations, budgets, and email administration.
billingManaging spend budgets.
memberHolding Brain grants that target a role.
viewerNothing beyond reading.

Some namespaces, such as evaluations, observability, and Brains, have no role restriction. Token scopes and their own resource grants control them. Service accounts have no role. A request with an API key gets only the scopes that both the key and its service account hold.

Authentication shows how credentials carry scopes and how to check what you can do.

Tenant headers select the scope of a request

Requests name the organization, project, and environment they act on with headers:

HeaderSelects
x-deployments-organizationAn organization ID
x-deployments-projectA project ID
x-deployments-environmentAn environment ID

Each operation's reference page lists the headers it needs. The CLI sends them from its context, and the SDK takes them in each call's headers.

Reference

On this page