API · POST
POST /v1/agents
Create a new agent — a versioned, scoped, policy-bound autonomous actor.
Overview
POST /v1/agents
Creates an agent with a role, tool allowlist, memory scope and approval policy. The agent enters draft state and must be promoted before it can be invoked in production.
All xyner API calls require an OAuth2 bearer token with the appropriate scope. Every request is identity-bound and audit-captured.
Request
Example request
{
"name": "claims-triage-agent",
"role": "claims-handler",
"model_routing": "policy:claims-tier",
"tools": ["policy-admin", "fraud-scoring", "guidewire-claims"],
"memory_scope": "claim",
"approval_policy": "threshold:0.85",
"rbac_inherit": true,
"audit_class": "claims"
}
Response
Example response
A successful response has shape:
{
"id": "agt_01H8Z3K9P5N6R7V8W0",
"version": "1.0.0",
"state": "draft",
"created_at": "2026-04-12T09:14:22Z",
"created_by": "usr_01HQX",
"name": "claims-triage-agent",
"promotion_url": "/v1/agents/agt_01H8Z3K9P5N6R7V8W0/promote"
}
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.