> ## Documentation Index
> Fetch the complete documentation index at: https://agents-docs.hockeystack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Send your first message to a deal agent with the Revenue Agents API.

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:

```bash theme={null}
export HS_TOKEN=hsr_live_...
export HS_BASE=https://app.hockeystack.com/api/revenue-agents/v1
export DEAL_ID=<your-deal-id>
```

<Tip>
  Prefer an MCP client over raw HTTP? Skip to [MCP server](/api/mcp-server) — it
  exposes the same endpoints as tools that Claude, Cursor, and others can call
  directly.
</Tip>

## 1. Verify the token

Call `/me` to confirm the token works and to see which workspace it belongs
to:

```bash theme={null}
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.

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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:

```json theme={null}
{
  "job_id": "8c1f…",
  "conversation_id": "…",
  "status": "pending",
  "poll_url": "/api/revenue-agents/v1/deals/.../conversations/.../messages/jobs/8c1f…"
}
```

Save the job ID:

```bash theme={null}
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:

```bash theme={null}
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](/api-reference). For changes that affect existing integrations,
see the [changelog](/api/changelog).