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

# Developers overview

> The Solya POS REST API: one backend behind both apps, agent-ready and generated from the live OpenAPI spec.

The Solya POS API is the same backend that powers the Centrale and the Caisse,
documented. Anything the two apps can do, an integration — or an AI agent — can do
through the API.

## What the API is

* A **REST API** over the Fastify backend, versioned under `/v1`.
* **Generated from the live spec** — the OpenAPI 3.0 document is generated at boot
  and served at `GET /openapi.json`, with Swagger UI at `GET /docs`. Only operations
  that opted into documentation appear, so the served surface is intentional.
* **Agent-ready** — every documented operation carries an `operationId`, an
  agent-facing `description`, the `pos.*` scopes it enforces
  (`x-required-permissions`) and an agent-usability tier (`x-agent-tier`).

## Start here

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/en/developers/authentication">
    Send a bearer token — a Keycloak access token or an opaque POS session token.
  </Card>

  <Card title="Making requests" icon="paper-plane" href="/en/developers/making-requests">
    Base URL, the success and error envelopes, and pagination.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/en/developers/error-codes">
    The `ResultCode` → HTTP status map, and the error body shape.
  </Card>

  <Card title="Agent & MCP" icon="robot" href="/en/developers/agent-mcp">
    The agent-tier and required-permission extensions, and the discovery flow.
  </Card>
</CardGroup>

## The API Reference

The full, per-operation reference — every path, parameter and schema — is generated
from the OpenAPI spec and browsable under the **API Reference** tab. This Developers
section is the conceptual guide that sits alongside it.