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.

The REST API Explorer is a Swagger UI interface for browsing and testing your app’s auto-generated REST endpoints. Open the Backend Console, switch to the REST API Explorer, and every endpoint your Data Model generates is listed with its parameters, request schema, response schema, and a “try it now” button that issues real requests with your current authentication. The REST API runs alongside the GraphQL API, shares the same authentication and permission model, and follows industry standards: RFC 9110 (HTTP semantics), RFC 9457 (Problem Details errors), and RFC 7396 (JSON Merge Patch). REST API Explorer

​
What’s in the Explorer

  • Endpoint list — every generated endpoint, grouped by table.
  • Schema panels — request and response schemas, including the constraints from your Data Model.
  • Try it now — fire a real request from the browser and inspect the live response.
  • OpenAPI link — fetch the auto-generated OpenAPI 3.1 spec for code generation and external tooling.

​
Base URL and resources

https://your-gateway.example.com/gw/api/rest
Every table is exposed as a resource at /<tableName>. For example: 
GET    /api/rest/students
GET    /api/rest/students/{id}
POST   /api/rest/students
PATCH  /api/rest/students/{id}
DELETE /api/rest/students/{id}
Table names use the exact name from the Data Model. The base URL is per-environment — see Environments.

​
Required headers

HeaderRequiredDefaultDescription
AuthorizationYes—Bearer <token> (JWT or API key)
X-Project-IDYes—Your project identifier
Content-TypeOn write—application/json for POST/PATCH bodies
environmentNomasterTarget environment name
X-Project-ID can also be sent as a query parameter (?project_id=...). The environment header also accepts the alias x-environment.

​
Authentication

The REST API accepts two token formats — both go in the Authorization: Bearer ... header:
  • JWT access token — issued by an authentication provider configured in App Services → Authentication Providers. Use this for end-user sessions in your client app.
  • API key — issued from Settings → API Keys, scoped per environment. Use these for server-to-server integrations and CI tooling.
curl -X GET "https://your-gateway.example.com/gw/api/rest/students" \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id"
API keys are environment-scoped — a key generated for dev cannot read master. When using an environment-scoped key, set the environment header to match.

​
Per-environment endpoints

The base URL and the API key set are per-environment. To target a non-default environment, send the environment header: 
curl -X GET "https://your-gateway.example.com/gw/api/rest/students" \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id" \
  -H "environment: dev"
If the header is omitted, requests default to master. See Environments.

​
Content types

OperationContent-Type
Createapplication/json
Updateapplication/merge-patch+json (preferred) or application/json
Delete—

​
The Prefer header

Prefer controls response shape and counting behavior:
ValueEffect
count=exactInclude exact totalCount in pagination metadata. Slower for large tables.
count=estimatedApproximate totalCount from database statistics. Fast.
count=noneOmit totalCount (default). Fastest.
return=representationReturn the full record in the response body (default).
return=minimalSuppress the response body, return status only.
curl -X GET "https://your-gateway.example.com/gw/api/rest/students" \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id" \
  -H "Prefer: count=exact"

​
Rate limiting

REST requests are rate-limited per project. When the limit is exceeded, the API responds 429 Too Many Requests with rate-limit headers — see Error handling.

​
CORS

CORS policy is per-project, configured under Settings → Network. The REST API and GraphQL API share the same allowed origins.

​
Permissions

Every endpoint enforces the per-role permissions defined in Role-Based Access. A user without read access to a field doesn’t see it in responses; a user without write access to a table receives 403 Forbidden on writes.

​
Where to go next

Queries

Read records — single, list, filtered, paginated, sorted, aggregated.

Mutations

Create, update, and delete — including bulk and update-by-filter.

Error handling

The Problem Details error format and what each status means.

File management

Upload, list, download, and delete files.

Idempotency

Retry POSTs safely with Idempotency-Key.

OpenAPI specification

The auto-generated spec and code-gen workflow.

Webhooks

Subscribe to data changes and deliver them to your services.

​
FAQ

Both expose the same data, the same permissions, and the same auth model. REST is best for tools that don’t speak GraphQL, server-to-server integrations, and idempotent writes. GraphQL is best for nested reads, real-time subscriptions, and clients that want to fetch exactly what they need. See GraphQL API Explorer.
Either include the X-Project-ID header on every request, or send it as a query parameter (?project_id=...). The Explorer fills it in automatically — outside the Explorer you have to provide it.
The endpoint shapes are stable per project. Schema changes (new tables, new fields) update the endpoints in real time and are reflected in the OpenAPI spec. Breaking changes to existing fields require explicit Data Model edits.
Yes. The OpenAPI specification is auto-generated and can be fed into tools like openapi-generator or openapi-typescript to produce a typed SDK in any language.
Under Settings → Network. The same allowed-origins list applies to the REST and GraphQL APIs.