API access

By the end of this page you will have created an API key and know how to call a deployed agent from your own code.

Prerequisites

• Admin role.
• A deployment with at least one agent. See Managing agents.

API keys

Programmatic access to a deployment uses API keys. A key is a secret token (prefixed qr_) that you send with each request. Keys are:

• Scoped — each key grants only the actions you choose.
• Shown once — the full key is displayed only at creation. Store it securely; you can’t view it again.
• Expirable and revocable — set an expiry, and rotate or revoke at any time.

The API Keys tab

Open a deployment and select API Keys to see active keys — each with its name, prefix, scopes, expiry, and last-used time.

Creating a key

Open the create dialog

Click Create Key and give it a descriptive name (for example, bi-dashboard).

Choose a scope and expiry

Pick the scope the key needs and how long it should live.

Copy the key

The full key is shown once. Copy it now and store it in your secret manager — you won’t be able to see it again.

Scopes

Calling a deployment

Send requests to the deployment’s base URL with your key in the Authorization header:

# AI Agent — the conversation endpoint returns the reply directly
curl https://your-deployment.qraptor.app/agents/{agentId}/conversation \
  -H "Authorization: Bearer qr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What was total revenue on 2026-07-20?" }'

The exact endpoints depend on the agent type — open an agent’s Endpoints panel in the Agents tab to copy its URLs.

AI Agent endpoints

run, conversation, and stream all return the reply directly — pick stream when you want tokens as they generate, conversation when you need memory across turns, run for a one-shot call.

Task Agent endpoints

A Task Agent runs a graph, which is asynchronous — you trigger it, then read the result:

Agent-to-agent (A2A) endpoints

Available only when A2A is enabled on an AI Agent. qRaptor implements the A2A protocol over JSON-RPC 2.0 — the message/send generation, which covers A2A 0.2.x and 0.3.0. Any compliant A2A client works, including agent frameworks such as Google ADK and LangGraph.

Discovery is public; the JSON-RPC endpoint needs an API key with the a2a scope — a separate key from invoke, since the Create Key dialog gives each key one scope.

Flow: a calling agent fetches the card, then POSTs message/send to the url the card advertises. The reply is a Task carrying the agent’s answer in result.artifacts:

curl -X POST https://your-deployment.qraptor.app/agents/{agentId}/a2a \
  -H "Authorization: Bearer qr_your_a2a_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "kind": "text", "text": "What was total revenue on 2026-07-20?" }],
        "messageId": "msg-0001"
      }
    }
  }'

See A2A integration for the full reference: version support, streaming, long-running tasks, error codes and client walkthroughs.

Multi-agent systems

A deployed system is called at its own endpoint — /mas/{systemId}/conversation/stream (POST, SSE). The router dispatches to the right member internally.

Triggering a Task Agent, then reading the result

A Task Agent’s POST /run is asynchronous — it starts the run and returns a run id immediately, not the final output:

# 1. Trigger — needs the `invoke` scope
curl -X POST https://your-deployment.qraptor.app/agents/{agentId}/run \
  -H "Authorization: Bearer qr_invoke_key" \
  -H "Content-Type: application/json" \
  -d '{ "execution_mode": "production" }'
# → { "run_id": "…", "status": "queued" }
 
# 2. Poll the result — needs the `runs:read` scope
curl https://your-deployment.qraptor.app/agents/{agentId}/runs/{run_id} \
  -H "Authorization: Bearer qr_runs_read_key"

Rotating and revoking

• Rotate — issues a new key and revokes the old one. Update your integrations with the new key.
• Revoke — disables a key immediately. Any request using it starts failing.

Common issues

• 401 Unauthorized — the key is missing, revoked, expired, or for a different deployment.
• 403 Forbidden — the key’s scope doesn’t cover the action. Create a key with the right scope.
• 429 Too Many Requests — you hit a rate limit.