Public API documentation Read as Markdown ↗

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. After your account is approved and active, create an API key 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.

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

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 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.

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:

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 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 for a complete Requests example that creates and polls a task. The same integration guide 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