> ## 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. # Initialize the deal agent (async) > Spawns the provisioning worker asynchronously and returns 202 immediately. Poll GET /deals/{dealId}/agent until `status` flips from `initializing` to `active` (success) or `provisioning_failed` (retry). Worker typically completes in 3–8 minutes. ## OpenAPI ````yaml https://app.hockeystack.com/api/revenue-agents/v1/openapi.json put /deals/{dealId}/agent openapi: 3.1.0 info: title: HockeyStack Revenue Agents API version: v1 description: | Headless HTTP API for HockeyStack Revenue Agents. Auth: Bearer ApiToken (`hsr_live_`) in the Authorization header. contact: name: HockeyStack Support email: support@hockeystack.com servers: - url: https://app.hockeystack.com/api/revenue-agents/v1 description: Production security: - bearerAuth: [] tags: - name: Service description: Health checks and token introspection. - name: Agents description: Deal- and company-agent lifecycle. - name: Conversations description: > Send messages to a deal or company agent. Two transports: - **REST blocking (default):** request returns when the agent finishes. Response shape: `{ conversation_id, messages: [...] }`. - **SSE streaming:** opt in via `Accept: text/event-stream` header or `{ stream: true }` body field. Events emitted: - `text_delta { content }` — incremental assistant tokens - `tool_use { id, tool_name }` — agent is calling a tool - `tool_result { id }` — tool finished (return value not exposed in v1) - `done { conversation_id, messages }` — final state, same shape as REST response - `error { code, category, message }` — failure - name: Tasks description: | Agent-generated and manually-created tasks. Public status enum: `pending | completed | dismissed | cancelled`. Additional internal states are not exposed. - name: Credits description: | Workspace credit usage and limit state. There is no pre-paid balance pool to draw down — the model is a per-month usage counter against an included bundle plus an optional on-demand cap. Use these endpoints to detect approaching spend caps before hitting a 503. paths: /deals/{dealId}/agent: parameters: - $ref: '#/components/parameters/DealId' put: tags: - Agents summary: Initialize the deal agent (async) description: > Spawns the provisioning worker asynchronously and returns 202 immediately. Poll GET /deals/{dealId}/agent until `status` flips from `initializing` to `active` (success) or `provisioning_failed` (retry). Worker typically completes in 3–8 minutes. operationId: putDealAgent requestBody: required: false content: application/json: schema: type: object description: Currently no body fields are honored. Reserved for v2. responses: '202': description: Provisioning started. content: application/json: schema: $ref: '#/components/schemas/AgentState' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': description: Provisioning already in flight for this deal. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' '500': description: Internal server error (e.g. spec misconfiguration). content: application/json: schema: $ref: '#/components/schemas/Error' '503': $ref: '#/components/responses/Unavailable' components: parameters: DealId: name: dealId in: path required: true description: CRM deal ID (HubSpot/Salesforce object ID). schema: type: string minLength: 1 maxLength: 64 schemas: AgentState: type: object required: - deal_id - status description: | Polymorphic agent-state envelope. Required fields: `deal_id` + `status`. Other fields' presence depends on `status`: - `active` — agent_id, created_at, last_synced_at populated - `initializing` — job_id, progress_stream_url populated; agent_id may be stale or null - `provisioning_failed` — job_id, failed_at, error, retry_with populated; agent_id null properties: deal_id: type: string status: type: string enum: - active - initializing - provisioning_failed description: > `active` — agent is provisioned and ready. `initializing` — async provisioning worker is in flight; poll until it flips. `provisioning_failed` — most recent provisioning run failed; PUT again to retry. agent_id: type: - string - 'null' created_at: type: - string - 'null' format: date-time last_synced_at: type: - string - 'null' format: date-time job_id: type: - string - 'null' progress_stream_url: type: string failed_at: type: - string - 'null' format: date-time error: type: - string - 'null' retry_with: type: string Error: type: object required: - error properties: error: type: object required: - code - category - message - request_id properties: code: type: string description: Stable error code. Never renamed or removed within /v1. category: type: string enum: - permanent - transient - rate_limited description: | `permanent` — fix the request. `transient` — retry with backoff. `rate_limited` — retry after the Retry-After header. message: type: string description: Human-readable English message. Wording may change. request_id: type: string description: Trace ID for support tickets. Same as X-Request-Id header. details: type: object description: Code-specific structured data. responses: BadRequest: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid token. content: application/json: schema: $ref: '#/components/schemas/Error' examples: tokenMissing: value: error: code: auth.token_missing category: permanent message: 'Missing Authorization: Bearer header.' request_id: req_abc tokenInvalid: value: error: code: auth.token_invalid category: permanent message: API token is invalid, expired, or revoked. request_id: req_abc RateLimited: description: Per-token or per-IP rate limit exceeded. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-RateLimit-Pool: $ref: '#/components/headers/RateLimitPool' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Error' Unavailable: description: An upstream dependency is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' headers: RetryAfter: description: Seconds until retry is allowed. schema: type: integer RateLimitPool: description: Pool that consumed a point for this request (`read` or `write`). schema: type: string enum: - read - write RateLimitLimit: description: Maximum requests allowed in the current window for this pool. schema: type: integer RateLimitRemaining: description: Requests remaining in the current window. schema: type: integer RateLimitReset: description: Unix timestamp when the bucket refills. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: hsr_live ````