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

# Overview

# API overview

**FinalSay** exposes an **Agent API** under `/v1/*` for **automations** (n8n, Zapier, scripts, MCP). It uses your **Agent ID** and **workspace API key** from the **web dashboard** or **mobile app**—not your personal login.

The **web dashboard** and **mobile app** use a separate private API with your user session to show agents, approvals, and settings. You do **not** need that API for integrations; use only the Agent API (or MCP tools that proxy to it) documented here.

## Other transports

| Approach | Notes                                                                                                                                                                                                         |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **REST** | Call `/v1/*` directly—see [Agent API](./agent).                                                                                                                                                               |
| **MCP**  | Same agent identity and backend; the FinalSay adapter exposes **`request_human_approval`**, **`create_approval`** (same create as the former), and **`get_approval_result`**. See [MCP](../integrations/mcp). |

## Who this is for

| You want to…                           | Use                                                                                                        |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Build workflows in n8n or Zapier       | [Agent API](./agent) with `X-Agent-Id` + `X-Api-Key` (or the [Zapier integration](../integrations/zapier)) |
| Use MCP tools from a compatible client | [MCP](../integrations/mcp) + same credentials                                                              |
| Use the product as a human approver    | [Web dashboard](../guide/web-dashboard) and/or [Mobile app](../guide/mobile-app)                           |

## Base URL

Use the HTTPS base URL provided by your deployment (for example `https://api.example.com`). All paths below are appended to that host.

## Agent authentication

Most `/v1` requests must include:

| Header       | Description                                                         |
| ------------ | ------------------------------------------------------------------- |
| `X-Agent-Id` | UUID of the **active** agent (from the web dashboard or mobile app) |
| `X-Api-Key`  | Full **workspace** API key (shown only once when generated)         |

**Exception:** `GET /v1/agents` lists agents for a key using **`X-Api-Key` only** (no `X-Agent-Id`). See [Agent API](./agent#get-v1agents).

Typical errors:

| HTTP | `error`                | Meaning                                                               |
| ---- | ---------------------- | --------------------------------------------------------------------- |
| 401  | `missing_agent_auth`   | Missing headers                                                       |
| 401  | `invalid_agent`        | Wrong or inactive agent                                               |
| 401  | `invalid_api_key`      | Key revoked or wrong team                                             |
| 403  | `USAGE_APPROVAL_LIMIT` | Approval create blocked by plan/subscription usage cap (when enabled) |
| 429  | `rate_limited`         | Too many creates in a short window                                    |

Details: [Agent API](./agent).

### Rate limits & quotas

* **Burst limit** on `POST /v1/approvals`: default **60** creates per **agent** per **60 seconds** (sliding window); deployments can change this. Exceeded → **429** `rate_limited`. See [Rate limits](./agent#rate-limits).
* **Plan / billing** caps (when enabled) → **403** `USAGE_APPROVAL_LIMIT`. See [Automation limits & billing](../guide/automation-limits).

### Callbacks & OpenAPI

* **Callback** contract (HTTP method, body shape, retries, no HMAC): [Callback webhooks](./agent#callback-webhooks).
* **OpenAPI 3** spec (download / tooling): [agent-api-openapi.yaml](./agent-api-openapi.yaml).

## Connectivity check

If your host exposes it, `GET /health` may return `{ "ok": true }` to verify the service is up. Availability depends on your environment.

## Related

* [Agent API](./agent) — full reference
* [n8n](../integrations/n8n) · [Zapier](../integrations/zapier) · [MCP](../integrations/mcp)
* [Credentials](../guide/credentials)