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

# Custom http

# Custom HTTP & scripts

Use any HTTP client (curl, scripts, backend jobs) with the [Agent API](../api-reference/agent). You need the same [Credentials](../guide/credentials) as n8n or Zapier: **Agent ID**, **workspace API key**, and your deployment **base URL** (no trailing slash on the host).

## Headers on every call

| Header         | Value                           |
| -------------- | ------------------------------- |
| `X-Agent-Id`   | Your agent UUID                 |
| `X-Api-Key`    | Your workspace API key          |
| `Content-Type` | `application/json` (for `POST`) |

## Create an approval (curl)

Replace placeholders and run:

```bash theme={null}
export BASE_URL="https://your-api.example.com"
export AGENT_ID="00000000-0000-0000-0000-000000000000"
export API_KEY="your-workspace-api-key"

curl -sS -X POST "$BASE_URL/v1/approvals" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: $AGENT_ID" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "question": "Deploy to production?",
    "context_markdown": "Build #123 passed CI.",
    "options": [
      { "label": "Approve", "value": "approve" },
      { "label": "Reject", "value": "reject" }
    ]
  }'
```

The JSON response includes **`request_id`** (use this for polling, even if you did not send `request_id` in the body). Optional fields (`timeout`, `callback`, `request_id`, …) are documented under [POST /v1/approvals](../api-reference/agent#post-v1-approvals).

## Poll for the result (curl)

```bash theme={null}
export REQUEST_ID="<request_id from create response>"

curl -sS "$BASE_URL/v1/approvals/$REQUEST_ID/result" \
  -H "X-Agent-Id: $AGENT_ID" \
  -H "X-Api-Key: $API_KEY"
```

While humans have not finished, the body looks like `{ "request_id": "...", "status": "pending" }`. When resolved, `status` is no longer `pending` and the payload includes outcome fields—see [GET result](../api-reference/agent#get-v1-approvals-requestid-result) and [Approval status values](../api-reference/agent#approval-status-values).

## Callback instead of polling

If you set `callback.url` on create, the service **POSTs the same JSON** as the final poll response when the approval completes. See [Callback webhooks](../api-reference/agent#callback-webhooks).

## Errors to handle

* **400** `invalid_payload` — Fix the JSON; check `issues` if present.
* **401** — Wrong agent or API key.
* **403** `USAGE_APPROVAL_LIMIT` — Plan / usage cap; see [Automation limits & billing](../guide/automation-limits).
* **409** `idempotency_conflict` — Same `request_id` with a different payload.
* **429** `rate_limited` — Slow down creates; see [Rate limits](../api-reference/agent#rate-limits).

## Related

* [Agent API](../api-reference/agent) — full field reference
* [OpenAPI specification](../api-reference/agent-api-openapi.yaml) — machine-readable description (YAML)
* [n8n](./n8n) · [Zapier](./zapier) · [MCP](./mcp)