OpenAPI specification

Every Archie project automatically generates an OpenAPI 3.1 specification covering every REST endpoint, request/response schema, and authentication scheme. The spec stays in sync with your Data Model — 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:

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"

{
  "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.

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

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 — generates pure type definitions, pairs well with openapi-fetch.
orval — 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.

FAQ

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.

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.

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.

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.

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.

Home

Blueprint

Design

Frontend

Backend

Assets

Where to get the spec

From the dashboard

From the API

What’s inside

Per-environment specs

Caching

Generating typed clients

TypeScript

Other languages

Importing into REST clients

Permissions

FAQ

​Where to get the spec

​From the dashboard

​From the API

​What’s inside

​Per-environment specs

​Caching

​Generating typed clients

​TypeScript

​Other languages

​Importing into REST clients

​Permissions

​FAQ

Where to get the spec

From the dashboard

From the API

What’s inside

Per-environment specs

Caching

Generating typed clients

TypeScript

Other languages

Importing into REST clients

Permissions

FAQ