Skip to main content

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.

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:
BehaviorValue
Cache-Controlpublic, max-age=300, stale-while-revalidate=30
StoragePersistent (S3)
RegenerationOn-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

ToolHow to import
PostmanNew → Import → Link → paste the spec URL. Postman generates a full collection with example requests.
InsomniaApplication menu → Import → URL → paste. Endpoints appear ready to fire.
Bruno, Hoppscotch, Thunder ClientAll 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

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