# Harnyx API quickstart

Create a research task, check its status, and read the answer with its sources. These docs are public: you can read them before signing in.

## Before your first request

Harnyx is an experimental alpha. [Create an account to request access](https://console.harnyx.ai/?mode=sign_up). After your account is approved and active, [create an API key](https://console.harnyx.ai/api-keys) and check that your account has credits.

Keep your key in a secret manager or environment variable named `HARNYX_API_KEY`. Never include it in a URL, research input, source control, or shared logs. Requests use `Authorization: Bearer <HARNYX_API_KEY>`.

## Create a task with cURL

Set `HARNYX_API_KEY` in your environment before running these commands. This example also uses `jq` to extract the task ID.

Generate one unique `HARNYX_IDEMPOTENCY_KEY` for this logical request and retain it with the exact request body. If a POST times out or its response is lost, retry with that same key and body; a new key could create another billable task. Use a new key only for new work.

```sh
curl --fail-with-body --silent --show-error \
  https://api.harnyx.ai/v1/research/tasks \
  -H "Authorization: Bearer $HARNYX_API_KEY" \
  -H "Idempotency-Key: $HARNYX_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{"input":"Compare the privacy and data-retention policies of Pinecone and Weaviate Cloud. Cite primary sources."}' \
  -o task.json
```

HTTP `202` means the task was accepted, not that research finished. The response contains its `id` and current `status`.

## Poll and read the result

```sh
curl --fail-with-body --silent --show-error \
  "https://api.harnyx.ai/v1/research/tasks/$(jq -r '.id' task.json)" \
  -H "Authorization: Bearer $HARNYX_API_KEY" \
  -o result.json

jq '{status, output, citations, error, credits_charged}' result.json
```

Wait between GET requests (for example, two seconds). Repeat until `status` is `completed` or `failed`; `queued` and `in_progress` mean work is still running. Back off after HTTP `429` instead of polling continuously.

On `completed`, read `output` and `citations`. Exact `[[n]]` markers point to `citations[n - 1]`; nullable citation positions must retain their numbering. Use `status` to determine success: structured output can validly be JSON `null`.

On `failed`, inspect `error.code` and `error.message`. Insufficient credits can fail a task after the create request was accepted. [The integration guide](https://harnyx.ai/docs/integrations#failed-task-errors) explains terminal errors separately from HTTP errors.

`credits_charged` is a decimal string such as `"0.10"`, not a floating-point number. It is `null` before the task reaches a terminal status. Inspect this field on every terminal task; completed tasks currently cost `"0.10"`, while a failed task may report `"0.00"`.

## Stream research progress

The same POST accepts `"stream": true`. It returns HTTP `200` with `text/event-stream`: first the task's current state, then tool-call progress and the final result. Omit `stream`, or set it to `false`, to keep the existing HTTP `202` JSON response.

```sh
curl --fail-with-body --silent --show-error --no-buffer \
  https://api.harnyx.ai/v1/research/tasks \
  -H "Authorization: Bearer $HARNYX_API_KEY" \
  -H "Idempotency-Key: $HARNYX_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{"input":"Compare the privacy and data-retention policies of Pinecone and Weaviate Cloud. Cite primary sources.","stream":true}'
```

Save the `task_id` in the initial `task.snapshot` event. If the connection ends before `task.completed` or `task.failed`, research continues. Reconnect to that task:

```sh
curl --fail-with-body --silent --show-error --no-buffer \
  "https://api.harnyx.ai/v1/research/tasks/$HARNYX_TASK_ID" \
  -H "Authorization: Bearer $HARNYX_API_KEY" \
  -H "Accept: text/event-stream"
```

Replaying POST with the same retained key and identical research input also returns the same task, and streams its current progress when `stream` is true. Changing delivery options does not create or charge another task. Connections close after five minutes; transport EOF alone does not mean research completed.

The [JavaScript example](https://harnyx.ai/docs/integrations#read-sse-events-from-javascript) reads named SSE events with the standard-compatible `eventsource` client. Browser `EventSource` supports cookie-authenticated GET; this client also supports the Bearer headers required by external integrations.

## Python and agent integrations

Follow the [Python quickstart](https://harnyx.ai/docs/integrations#call-the-api-from-python) for a complete Requests example that creates and polls a task. The same [integration guide](https://harnyx.ai/docs/integrations) covers JSON Schema output, safe retries, task listing, citations, credits, and MCP configurations for Codex, Claude Code, and VS Code.

The MCP endpoint is `https://api.harnyx.ai/mcp/research`. It uses API-key authentication and requires a client that supports configured HTTP authorization headers; hosted connectors that require OAuth cannot use it.

## Reference and machine-readable docs

- [API reference](https://harnyx.ai/docs/api): request and response schemas for the public Research Task endpoints.
- [Quickstart Markdown](https://harnyx.ai/docs/quickstart.md): this guide as plain Markdown.
- [Agent skill](https://harnyx.ai/skill.md): the complete integration guide as Markdown for your agent.
- [API reference Markdown](https://harnyx.ai/api/research.md): the generated schema reference.
- [OpenAPI JSON](https://harnyx.ai/api/research.openapi.json): the machine-readable public Research Task contract.
- [LLM documentation index](https://harnyx.ai/llms.txt): a concise list of these public sources.