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

# REST API Introduction

> 14 routes, enumerated from packages/api/src/app.ts. The full per-route reference is generated from openapi/openapi.yaml; this page covers what the spec can't express.

<Info>**\[AVAILABLE]**, every route below is mounted in `packages/api/src/app.ts`. No other routes exist.</Info>

## Base URL

Local: `http://localhost:3000` (see [Quickstart](/quickstart) for starting the server). The
raw spec is also served at `GET /openapi.yaml`, see [Deploy
patterns](/guides/deploy-patterns#the-openapi-spec-endpoint).

## Full reference

Every route, request/response shape, and status code is generated from
[`openapi/openapi.yaml`](https://github.com/pavancharak/parmana-exp/blob/main/openapi/openapi.yaml)
in the sidebar under **REST API**, each with real captured examples and a working curl
snippet. This page and its siblings cover what a spec can't express:

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    The bearer key model, and how it differs from Policy evaluation and gateway attestation.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/api-reference/error-handling">
    The shared error envelope, and two verified gaps in it.
  </Card>

  <Card title="Idempotency and nonces" icon="fingerprint" href="/api-reference/idempotency-and-nonces">
    Why there's no Idempotency-Key header, and what businessTransactionId does instead.
  </Card>

  <Card title="Error catalog" icon="list" href="/api-reference/error-catalog">
    Every error this API returns, one table, cross-linked from the spec.
  </Card>
</CardGroup>

## Errors

Non-2xx responses are `{ "error": string }`, sometimes with a `code` field. Full philosophy
and two verified gaps on [Error handling](/api-reference/error-handling); every specific
error this API returns on the [Error catalog](/api-reference/error-catalog).

Both maintained SDKs raise a specific exception per status code. The Python SDK:
`ValidationError`/`NotFoundError`/`ConflictError`/`ServerError`/etc., see [Python
SDK](/sdks/python). The TypeScript SDK: `ValidationError`/`AuthenticationError`/
`AuthorizationError`/`NotFoundError`/`ConflictError`/`ExecutionRejectedError`/etc., see
[TypeScript SDK](/sdks/typescript).

## Auth

<Info>**Every route requires a caller bearer key, except `GET /health`.** See
[Authentication](/api-reference/authentication) for how to send one and what it does and
does not prove.</Info>

## Rate limiting

`POST /execute` is rate-limited per authenticated caller; `GET /health` and `GET /ready` carry a
separate, more permissive limit keyed by IP. See [Authentication](/api-reference/authentication#rate-limiting)
for the mechanism and [Error catalog](/api-reference/error-catalog) for the exact `429` shape.