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

# OpenAPI specification

> Every project gets an auto-generated OpenAPI 3.1 spec that documents every endpoint, schema, and auth requirement — always in sync with your data model.

Every Archie project automatically generates an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) specification covering every REST endpoint, request/response schema, and authentication scheme. The spec stays in sync with your [Data Model](/features/backend/data-model/overview) — add a table or change a field and the spec regenerates.

The spec drives:

* The Swagger UI inside the **REST API Explorer**, which is generated from this same document.
* External tooling — Postman, Insomnia, code generators — that imports the spec to provide typed clients.

## Where to get the spec

### From the dashboard

Open **Backend → REST API Explorer**. The Swagger UI you see is built from the live spec for the selected environment. Browse endpoints, expand each operation, click **Try it out** to fire a request with your current authentication.

### From the API

Fetch the raw JSON with a `GET`:

```bash theme={null}
curl -X GET "https://your-gateway.example.com/gw/api/rest/_openapi.json" \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id"
```

```json theme={null}
{
  "openapi": "3.1.0",
  "info": {
    "title": "Archie Core REST API",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "/api/rest" }
  ],
  "paths": {
    "/students": { "get": { "..." }, "post": { "..." } },
    "/students/{id}": { "get": { "..." }, "patch": { "..." }, "delete": { "..." } }
  },
  "components": {
    "schemas": {
      "Students": { "..." },
      "StudentsInput": { "..." }
    }
  }
}
```

Paths in the spec are relative to `servers[0].url`. The gateway prefix (`/gw`) is handled at the infrastructure level.

## What's inside

The auto-generated spec includes:

* **Endpoints per table** — CRUD, bulk, aggregate, and the structured `_query` endpoint.
* **Per-table schemas** — `<TableName>` for responses, `<TableName>Input` for write payloads, generated from your column definitions.
* **Filter parameters** — every column with the operators it supports and example values.
* **Security schemes** — Bearer token (JWT) and API key.
* **Error schemas** — RFC 9457 Problem Details response shape.

## Per-environment specs

Each environment has its own spec — useful when a branch environment has Data Model changes that aren't yet in `master`.

```bash theme={null}
curl -X GET "https://your-gateway.example.com/gw/api/rest/_openapi.json" \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id" \
  -H "environment: dev"
```

See [Environments](/features/backend/environments/overview) for how environments work.

## Caching

The spec is cached for performance:

| Behavior        | Value                                                  |
| --------------- | ------------------------------------------------------ |
| `Cache-Control` | `public, max-age=300, stale-while-revalidate=30`       |
| Storage         | Persistent (S3)                                        |
| Regeneration    | On-demand when the cache expires or the schema changes |

You don't need to manually invalidate the cache — schema edits flow through automatically.

## Generating typed clients

The spec is the right input to any OpenAPI 3.1 code generator. A few examples:

### TypeScript

```bash theme={null}
npx openapi-generator-cli generate \
  -i "https://your-gateway.example.com/gw/api/rest/_openapi.json" \
  -g typescript-fetch \
  -o ./generated-client \
  --additional-properties=supportsES6=true
```

Other JS-friendly options:

* [`openapi-typescript`](https://github.com/drwpow/openapi-typescript) — generates pure type definitions, pairs well with `openapi-fetch`.
* [`orval`](https://orval.dev/) — generates React Query hooks alongside types.

### Other languages

`openapi-generator-cli` supports 50+ targets — Python, Go, Ruby, Java, C#, Swift, Kotlin, Rust. Pick the generator (`-g`) that matches your stack.

## Importing into REST clients

| Tool                                          | How to import                                                                                        |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Postman**                                   | New → Import → Link → paste the spec URL. Postman generates a full collection with example requests. |
| **Insomnia**                                  | Application menu → Import → URL → paste. Endpoints appear ready to fire.                             |
| **Bruno**, **Hoppscotch**, **Thunder Client** | All support OpenAPI import via URL or file.                                                          |

When importing, point the auth at your API key and `X-Project-ID` header so requests work out of the box.

## Permissions

The spec itself is not access-controlled per role — it describes the surface area available. Authentication is required to fetch it. Per-record and per-field permissions are enforced at request time by [Role-Based Access](/features/backend/app-services/role-based-access).

## FAQ

<AccordionGroup>
  <Accordion title="Does the spec include my custom functions or App Services endpoints?">
    The auto-generated spec covers Data Model endpoints — CRUD, bulk, aggregate, query, file management, webhooks. Custom functions and custom APIs that you write live alongside but are documented separately.
  </Accordion>

  <Accordion title="How fresh is the spec after a schema change?">
    Cached for 5 minutes with `stale-while-revalidate`. Schema changes regenerate the spec on the next fetch after the cache expires. To force-fresh, fetch from a different environment or wait the cache window out.
  </Accordion>

  <Accordion title="Is the spec OpenAPI 3.0 or 3.1?">
    3.1, which uses the latest JSON Schema draft for component schemas. Most modern tools support it; if you hit a generator that's still on 3.0, downgrade tools rather than the spec.
  </Accordion>

  <Accordion title="Can I publish the spec to my own developer portal?">
    Yes. Cache the JSON and serve it from your portal. For self-updating docs, fetch the spec on a schedule and re-deploy when it changes.
  </Accordion>

  <Accordion title="What's a good code-gen workflow for CI?">
    Pin the generator version, fetch the spec from your `master` environment, generate the client into a build artifact, and check that artifact into version control or publish as an internal package. Run the generator on every Data Model change.
  </Accordion>
</AccordionGroup>