> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.gooclaim.com/llms.txt.
> For full documentation content, see https://api.docs.gooclaim.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.gooclaim.com/_mcp/server.

# API Reference

Gooclaim exposes **four services** to TPA and Insurer partners. All other
Gooclaim services are internal and not callable from outside.

## The four services

Issues JWTs for all subsequent API calls. RS256-signed, short-lived.

Inspect, control, and observe workflow instances (Claim Status, Pending
Documents, Query Reason).

Tenant-scoped read access to the immutable audit ledger. For your own
IRDAI compliance reporting.

Event schemas for the webhooks Gooclaim pushes to you.

## Base URLs

| Environment | Base URL                       |
| ----------- | ------------------------------ |
| Production  | `https://api.gooclaim.com`     |
| Development | `https://api.dev.gooclaim.com` |

All business endpoints are mounted under `/v1/*`. Infrastructure endpoints
(`/health`, `/ready`, `/metrics`) stay at the root and are **not** part of
the partner API contract.

## Conventions

* **Auth** — `Authorization: Bearer <JWT>` on every request except
  `POST /v1/auth/token`.
* **Tenant scoping** — your JWT carries `tenant_id`. Every response is
  filtered to your tenant. You cannot read another tenant's data.
* **PHI safety** — claim IDs, phone numbers, and names are **hashed**
  (`sha256:...`) in any returned payload. If you need to correlate back to
  a plaintext identifier, do that in your own system.
* **Errors** — RFC 7807 problem-detail JSON, with a stable `error_code`
  string.
* **Idempotency** — mutating endpoints accept `Idempotency-Key` headers.

## Rate limits

| Endpoint family         | Limit                  |
| ----------------------- | ---------------------- |
| `POST /v1/auth/token`   | 60 / min / client\_id  |
| `GET  /v1/workflows/*`  | 600 / min / tenant\_id |
| `GET  /v1/audit/events` | 300 / min / tenant\_id |

Exceeding the limit returns `429 Too Many Requests` with a `Retry-After`
header.

## SDKs

Generated SDKs are planned for `v1.0`:

* Python (`pip install gooclaim`)
* Node.js (`npm install @gooclaim/sdk`)
* Go (`go get github.com/gooclaim-claimos/gooclaim-go`)

Hand-written SDKs are not maintained — always use the generated ones once
released.

## Need help?

* **Support** — [support@gooclaim.com](mailto:support@gooclaim.com)
* **Status** — [status.gooclaim.com](https://status.gooclaim.com)