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

# Overview

> The REST API Explorer is a Swagger UI interface for browsing and testing your app's auto-generated REST endpoints.

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](/features/backend/data-model/overview) 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](/features/backend/graphql-api-explorer/overview), shares the same authentication and permission model, and follows industry standards: [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) (HTTP semantics), [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (Problem Details errors), and [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396) (JSON Merge Patch).

<img src="https://mintcdn.com/archie-e998dbf6/GdaYz5W-YpQoJXsQ/features/backend/rest-api-explorer/rest-api-explorer.png?fit=max&auto=format&n=GdaYz5W-YpQoJXsQ&q=85&s=2a2330dabe2337f2b2000119f231279f" alt="REST API Explorer" width="1864" height="897" data-path="features/backend/rest-api-explorer/rest-api-explorer.png" />

## 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](/features/backend/rest-api-explorer/openapi-specification) for code generation and external tooling.

## Base URL and resources

```text theme={null}
https://your-gateway.example.com/gw/api/rest
```

Every table is exposed as a resource at `/<tableName>`. For example:

```text theme={null}
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](/features/backend/environments/overview).

## Required headers

| Header          | Required | Default  | Description                              |
| --------------- | -------- | -------- | ---------------------------------------- |
| `Authorization` | Yes      | —        | `Bearer <token>` (JWT or API key)        |
| `X-Project-ID`  | Yes      | —        | Your project identifier                  |
| `Content-Type`  | On write | —        | `application/json` for POST/PATCH bodies |
| `environment`   | No       | `master` | Target 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](/features/backend/app-services/authentication-providers/overview). 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.

```bash theme={null}
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:

```bash theme={null}
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](/features/backend/environments/overview).

## Content types

| Operation | Content-Type                                                     |
| --------- | ---------------------------------------------------------------- |
| Create    | `application/json`                                               |
| Update    | `application/merge-patch+json` (preferred) or `application/json` |
| Delete    | —                                                                |

## The Prefer header

`Prefer` controls response shape and counting behavior:

| Value                   | Effect                                                                      |
| ----------------------- | --------------------------------------------------------------------------- |
| `count=exact`           | Include exact `totalCount` in pagination metadata. Slower for large tables. |
| `count=estimated`       | Approximate `totalCount` from database statistics. Fast.                    |
| `count=none`            | Omit `totalCount` (default). Fastest.                                       |
| `return=representation` | Return the full record in the response body (default).                      |
| `return=minimal`        | Suppress the response body, return status only.                             |

```bash theme={null}
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](/features/backend/rest-api-explorer/error-handling#rate-limit-exceeded-429).

## 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](/features/backend/app-services/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

<CardGroup cols={2}>
  <Card title="Queries" icon="magnifying-glass" href="/features/backend/rest-api-explorer/queries">
    Read records — single, list, filtered, paginated, sorted, aggregated.
  </Card>

  <Card title="Mutations" icon="pen-to-square" href="/features/backend/rest-api-explorer/mutations">
    Create, update, and delete — including bulk and update-by-filter.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/features/backend/rest-api-explorer/error-handling">
    The Problem Details error format and what each status means.
  </Card>

  <Card title="File management" icon="paperclip" href="/features/backend/rest-api-explorer/file-management">
    Upload, list, download, and delete files.
  </Card>

  <Card title="Idempotency" icon="rotate" href="/features/backend/rest-api-explorer/idempotency">
    Retry POSTs safely with `Idempotency-Key`.
  </Card>

  <Card title="OpenAPI specification" icon="file-code" href="/features/backend/rest-api-explorer/openapi-specification">
    The auto-generated spec and code-gen workflow.
  </Card>

  <Card title="Webhooks" icon="bell" href="/features/backend/rest-api-explorer/webhooks">
    Subscribe to data changes and deliver them to your services.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="REST or GraphQL — which should I use?">
    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](/features/backend/graphql-api-explorer/overview).
  </Accordion>

  <Accordion title="Why am I getting `400 Missing X-Project-ID`?">
    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.
  </Accordion>

  <Accordion title="Are the REST endpoints versioned?">
    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.
  </Accordion>

  <Accordion title="Can I generate a typed client from the API?">
    Yes. The [OpenAPI specification](/features/backend/rest-api-explorer/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.
  </Accordion>

  <Accordion title="Where do I configure CORS for my frontend?">
    Under **Settings → Network**. The same allowed-origins list applies to the REST and GraphQL APIs.
  </Accordion>
</AccordionGroup>