Developer documentation

Everything you need to authenticate, create your first agent, and wire up webhook events. Full SDK reference and guides ship alongside GA of the public API.

Overview

The AgentForge API is a REST API over HTTPS. All requests and responses use JSON. The base URL for all API calls is:

https://api.qxentrixai.com/v1

API access is currently issued to design-partner accounts directly — request a key to get started.

Authentication

Every request must include your API key as a bearer token in the Authorization header. Keys are scoped to an environment (test or live) and can be rotated from the dashboard without downtime.

cURL

curl https://api.qxentrixai.com/v1/agents \
  -H "Authorization: Bearer qx_live_••••••••••••"

Sandbox & Live environments

Every account has two isolated environments. Build and test against Sandbox with fabricated data and no Bedrock inference charges, then switch to Live when you're ready for real traffic — same API, same agent config, different key prefix.

Sandbox

Live

cURL · Sandbox

curl https://api.qxentrixai.com/v1/agents \
  -H "Authorization: Bearer qx_test_51fK9x••••••"

Sandbox

Uses qx_test_ keys
Synthetic tool responses — no real Zendesk/CRM calls
No Bedrock inference cost billed to your account
Rate limit: 5,000 invocations / day

Live

Uses qx_live_ keys
Tool calls hit your real, configured endpoints
Billed per your plan's included invocations + overage
Rate limit: per your plan tier

Agents and their versions are shared across both environments — only the key and the data they touch differ. Promote a version to Live the same way regardless of which environment you tested it in.

Create an agent

Method	Path	Description
POST	/v1/agents	Create a new agent definition (unversioned draft)

Request body

{
  "name": "support-agent-v1",
  "model": "bedrock:anthropic.claude",
  "tools": ["zendesk", "order_lookup"],
  "memory": "session",
  "guardrails": "default-support-v1"
}

List agents

Method	Path	Description
GET	/v1/agents	List agents in the current environment, paginated
GET	/v1/agents/:id	Retrieve a single agent and its version history
DELETE	/v1/agents/:id	Archive an agent (existing endpoint returns 410)

Response

{
  "data": [
    { "id": "agt_8fJ2...", "name": "support-agent-v1", "live_version": 3 }
  ],
  "next_cursor": "eyJpZCI6..."
}

Invoke an agent

Method	Path	Description
POST	/v1/agents/:id/invoke	Run the agent's live version against an input

Python SDK

from qxentrix import Qxentrix

client = Qxentrix(api_key="qx_live_...")
result = client.agents.invoke(
    "support-agent-v1",
    input="Where is order #48213?"
)
print(result.output)

Webhook events

Register a webhook URL per environment to receive lifecycle and runtime events. Payloads are signed with an HMAC signature in the Qx-Signature header.

Event	Fired when
agent.deployed	A new agent version is promoted to live
agent.invocation.completed	An invocation finishes successfully
agent.invocation.failed	An invocation errors out after retries
agent.guardrail.triggered	A guardrail policy blocks or redacts a response
agent.handoff.requested	An agent hands off to a human per its handoff rules

Error codes

Status	Meaning
400	Malformed request body or invalid tool schema
401	Missing or invalid API key
403	Key valid but not scoped for this environment
404	Agent or version not found
409	Version conflict on deploy
429	Rate limit exceeded for this key
500	Internal error — check status page and retry with backoff

SDKs

TypeScript / Node

npm install @qxentrix/sdk

Python

pip install qxentrix