API · POST
POST /v1/deployments
Promote an agent version to an environment with a canary or staged rollout.
Overview
POST /v1/deployments
Deploys an agent version to a target environment. Supports canary, percentage-based and immediate promotion strategies, with automatic rollback on metric breach.
All xyner API calls require an OAuth2 bearer token with the appropriate scope. Every request is identity-bound and audit-captured.
Request
Example request
{
"agent_id": "agt_01H8Z3K9P5N6R7V8W0",
"version": "1.4.0",
"environment": "production",
"strategy": "canary",
"canary_percentage": 10,
"auto_rollback_metrics": {
"policy_denial_rate_p99": 0.02,
"error_rate_p99": 0.01
}
}
Response
Example response
A successful response has shape:
{
"deployment_id": "dep_01H9B",
"state": "rolling_out",
"started_at": "2026-04-12T09:30:00Z",
"rollback_url": "/v1/deployments/dep_01H9B/rollback",
"metrics_url": "https://app.xyner.ai/deployments/dep_01H9B"
}
Notes
Things worth knowing
Useful behavioural details for this endpoint.
- All endpoints support OpenTelemetry trace-context propagation via standard W3C headers.
- Idempotency keys are honoured for 24 hours (or longer for endpoints that explicitly support extended idempotency).
- Errors follow RFC 7807 problem+json with a stable error code in
type. - Every successful action produces one or more audit records, queryable via /v1/audit/query.
- Rate limits apply per-tenant; current limits are returned in
X-RateLimit-*response headers.
See also
Related endpoints and concepts
This endpoint is part of the broader xyner platform API. For an end-to-end view, see the platform overview and the documentation hub.
Get started
Ready to put autonomous agents to work?
See xyner in your environment with a guided executive demo.