Deployments and discovery API
Upload immutable executable packages, poll builds, and discover Agents, Channels, Auth Providers, providers, and Console catalog data.
Deploy executable packages
| Method | Path | Authority | Purpose |
|---|---|---|---|
POST | /v1/deployments | deployment:create | Upload a raw ZIP or tar.gz package |
GET | /v1/deployments/:deploymentId | deployment:read | Read build, probe, publication, or failure state |
GET | /v1/namespaces/:namespace/agents/:agent/rollout | agent:read | Read the active or most recent canary |
POST | /v1/namespaces/:namespace/agents/:agent/rollout/promote | deployment:create | Promote the exact active candidate |
POST | /v1/namespaces/:namespace/agents/:agent/rollout/rollback | deployment:create | Close the canary without changing current |
The upload content type is application/zip or application/gzip. Supply Bearer deployment authority and a stable Idempotency-Key. The root contains exactly one accepted manifest plus package.json and imported TypeScript source. Credential Provider packages also contain their root configuration schema. A successful result pins deployment revision, executable artifact, code digest, compatibility evidence, registry publication, and sourcePackage. The source package is a normalized tar.gz artifact owned by the deployment tenant and namespace; governed CAS and Sandbox workflows can reuse it by content reference without receiving storage credentials or relying on the original upload format.
Immediate activation is the default. To create an Agent canary, append rollout=canary, a decimal fraction greater than zero and less than one, and optionally tags, a URL-encoded JSON string map. The idempotency identity includes the archive and rollout controls. Canary is rejected for non-Agent packages and for an Agent without a current control revision.
Promote and rollback bodies contain deploymentRevision, eventId, and a bounded reason. The authenticated principal becomes the recorded actor. Both operations are idempotent for the same event and fail on a stale current pointer.
Deployment outputs
A deployment that publishes more than one Resource carries an outputs array on its record. Project builds list every published Resource; a single Agent whose manifest declares a ui block lists the Agent at ordinal 0 and the UI at ordinal 1. Top-level resourceCrn and resourceHash stay Agent-centric, so read the UI from outputs.
| Field | Meaning |
|---|---|
ordinal | Position in the deployment; 0 is the primary Resource |
resourceKind | agent, ui, or another published kind |
resourceId, namespace | Resource identity |
resourceCrn, resourceHash | Exact published revision |
codeDigest | The executable code digest, or the bundle content address for a UI |
resource | The output identity: for a UI it includes url, routeId, bundleRef, manifestHash, target.agent, target.channel, access.mode, execution.mode, and deploymentRevision |
curl https://platform.constal.ai/v1/deployments/$DEPLOYMENT_ID \
-H "Authorization: Bearer $CONSTAL_DEPLOYMENT_KEY" \
| jq -r '.data.outputs[] | select(.resourceKind == "ui") | .resource.url'Deployments with a ui block accept only immediate activation; rollout=canary and candidate builds are rejected before any upload.
Discover deployed definitions
| Method | Path | Purpose |
|---|---|---|
GET | /v1/namespaces/:namespace/agents | List deployed Agents |
GET | /v1/namespaces/:namespace/agents/:agent | Read one Agent identity and accepted configuration |
GET | /v1/namespaces/:namespace/channels | List deployed Channels |
GET | /v1/namespaces/:namespace/channels/:channel | Read one Channel |
GET | /v1/namespaces/:namespace/console/catalog | Retrieve the Console’s authorized combined catalog projection |
GET | /v1/health | Read public service health |
Credential Provider package discovery and installation are covered by Credential HTTP API. Tenant-managed integration implementations and contracts are covered by Resources and bindings. Git repository deployment is a Console workflow that resolves a public repository at an exact commit and submits its bounded archive through the same builder path.