Skip to main content
This guide walks you from zero to a working agent response. You will verify a token, initialize a deal agent, open a conversation, send a message, and read the result. The whole flow takes about ten minutes, most of which is waiting for agent provisioning.

​
Before you start

You need:
  • A HockeyStack workspace on a plan with API access.
  • A Revenue Agents API token. Generate one in workspace settings — it looks like hsr_live_<hex>. Treat it like a password.
  • A deal ID from your CRM. Any open or recently-closed deal works.
All examples below use curl. The base URL is https://app.hockeystack.com/api/revenue-agents/v1. Export the basics so the snippets stay short: 
export HS_TOKEN=hsr_live_...
export HS_BASE=https://app.hockeystack.com/api/revenue-agents/v1
export DEAL_ID=<your-deal-id>
Prefer an MCP client over raw HTTP? Skip to MCP server — it exposes the same endpoints as tools that Claude, Cursor, and others can call directly.

​
1. Verify the token

Call /me to confirm the token works and to see which workspace it belongs to: 
curl -sS "$HS_BASE/me" \
  -H "Authorization: Bearer $HS_TOKEN"
A 200 with your workspace metadata means you are good to go. A 401 means the token is missing, malformed, or revoked.

​
2. Initialize the deal agent

Each deal needs an agent provisioned once. This is asynchronous — the PUT returns immediately and the worker takes about 3–8 minutes. 
curl -sS -X PUT "$HS_BASE/deals/$DEAL_ID/agent" \
  -H "Authorization: Bearer $HS_TOKEN"
You get back 202 with status: "initializing". Poll the same path until status flips to active: 
curl -sS "$HS_BASE/deals/$DEAL_ID/agent" \
  -H "Authorization: Bearer $HS_TOKEN"
Terminal states:
  • active — ready for messages.
  • provisioning_failed — retry the PUT.
If the agent already exists for this deal, the PUT returns 409. That is fine — skip to the next step.

​
3. Open a conversation

A conversation groups a sequence of messages with the same agent. Create one: 
curl -sS -X POST "$HS_BASE/deals/$DEAL_ID/conversations" \
  -H "Authorization: Bearer $HS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
The response contains a conversation_id. Save it: 
export CID=<conversation_id>

​
4. Send a message

POST to the conversation. This returns 202 immediately with a job handle — the agent runs in the background. 
curl -sS -X POST "$HS_BASE/deals/$DEAL_ID/conversations/$CID/messages" \
  -H "Authorization: Bearer $HS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "What is the single biggest risk on this deal right now?"}'
Sample response: 
{
  "job_id": "8c1f…",
  "conversation_id": "…",
  "status": "pending",
  "poll_url": "/api/revenue-agents/v1/deals/.../conversations/.../messages/jobs/8c1f…"
}
Save the job ID: 
export JOB_ID=<job_id>

​
5. Poll for the result

Poll the job endpoint on a 1–5 second interval until status lands in a terminal state: 
curl -sS "$HS_BASE/deals/$DEAL_ID/conversations/$CID/messages/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HS_TOKEN"
Terminal states:
  • completed — read the assistant reply from result.messages.
  • failed — read error.code, error.category, and error.message.
Jobs are retained for 60 minutes while pending and 15 minutes after a terminal state, then return 404. Read the result before that window closes.

​
What to try next

  • Streaming instead of polling — send the same POST with Accept: text/event-stream (or { "stream": true } in the body) to receive text_delta, tool_use, and done events in real time.
  • Company agents — every endpoint above has a /companies/{companyId}/… counterpart with the same shape.
  • Tasks — GET /tasks lists the agent-generated next actions. Mark them completed or dismissed to feed the learning loop.
  • Credits — GET /credits/balance reports usage against your monthly bundle. Watch this to avoid 503 once the cap is reached.
For complete request and response shapes, see the API reference. For changes that affect existing integrations, see the changelog.