---
title: "Ductor programmatoris"
description: "API REST Quire, OAuth, retia textoria, servitium MCP et extensiones."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/la/llms.txt
> Use this file to discover all available pages before exploring further.

# Ductor programmatoris

<span id="developer-guide"></span>

Utere addressa API collegii tui et signo ambitu instructo. Incipe a petitione
legendi, responsum inspice, et arcana extra custodiam codicis et exemplaria
documentationis serva.

Quire unam API publicam habet: REST super HTTPS, descriptam documento OpenAPI
3.1, cum retibus textoriis signatis pro eventibus et servitio MCP pro adiutoribus
AA. [Referentia API](https://docs.quirelms.com/api/) omne punctum terminale et omne eventum enumerat.

## Addressa <!--quire:addresses-->

Quodque collegium propriam addressam habet, et API sub ea vivit:

```
https://acme.quirelms.com/api/v1/courses
```

Signum collegium decidit. Clavis pro uno collegio in addressa alterius usa
refuitur.

Documento OpenAPI in `/api/v1/openapi.json` in addressa cuiusque collegii
praebetur, ita ut generatores clientium semper eam versionem videant quam vocas.

## Authenticatio <!--quire:authentication-->

**Claves API** pro scriptis et integrationibus inter ministratores sunt. Una
administrator in `/admin/integrations/api-keys` creat, ambitus eius eligit, et
eam semel videt. Eam ut signum ferentem mitte:

```
curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50
```

Claves `qk_live_` aut `qk_test_` incipiunt. Quaeri integrationi tuam propriam
clavem da.

**OAuth 2.1** pro applicationibus est quae ut persona consessa agunt. Clientem
in `/admin/integrations/oauth-clients` inscribe, deinde fluxum codicis
auctorizationis cum PKCE (`/oauth/authorize`, `/oauth/token`) utere, aut
indicium clientis pro cliente machinali. Inquisitio in
`/.well-known/oauth-authorization-server` est. Ambitus id angustat quod signum
facere possit; numquam plus facere sinit quam persona posset.

Ambitus sunt `resource:read`, `resource:write` et `resource:delete`, verbi
causa `courses:read` aut `enrolments:write`. Quattuor privilegiati sunt et cum
monitione in facie consensus monstrantur: `audit:read`, `roles:write`,
`tenants:write` et `users:delete`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-api-keys.webp" alt="The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another." width="944" height="700" loading="lazy" decoding="async"><figcaption>API keys list who each key acts as and what it may reach.</figcaption></figure>

## Petitiones <!--quire:requests-->

- **Paginatio**: quaelibet lista paginatur in indice cursoris. Trahe `limit`,
  deinde `next_cursor` ex `page` ut `cursor` dum `has_more` verum est (exemplum
  infra). Nulla offset est.
- **Mutationes ex**: `updated_since` reddit id quod post tempus mutatum est.
  Ei `include_deleted=true` iunge, aut `/<resource>/deletions` lege, ut scias
  quid remotum sit.
- **Identificatores externi**: pleraque rerum tuum proprium `external_id`
  accipiunt, et `/<resource>/ext:{external_id}` eo legit aut inserit, ita ut
  sync numquam identificatores Quire servare egeat.
- **Idempotentia**: mitte caput `Idempotency-Key` in `POST`, `PATCH` et
  `DELETE`. Iteratio cum eadem clave primum responsum reddit potius quam opus
  bis faciat. Puncta terminalia massa id requirunt.
- **Versiones**: versio maior in via est (`/v1`). Intra eam quaeque mutatio
  frangens revisio data instruitur, cum capite `Quire-Version` electa, verbi
  causa `Quire-Version: 2026-09-20`. Sine capite eam versionem quae cum signum
  tuum datur vigebat accipis.

Pagina listae:

```
{"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}}
```

## Errores <!--quire:errors-->

Quisque error documentum problematis RFC 9457 est:

```
{"type": "https://quire.com/errors/enrolment.seat_limit_reached",
 "title": "Seat limit reached", "status": 409,
 "code": "enrolment.seat_limit_reached", "category": "conflict",
 "detail": "The course has no seats left, so this enrolment was not created. ...",
 "request_id": "01JB7XQK4Z..."}
```

In `code` divide, quod stabile est; `detail` hominibus scriptum est, iis
monstrare tutum, et mutari potest. Cum codicem non agnoveris, in `category`
divide:

| Categoria | Status | Iterum |
| --- | --- | --- |
| `validation` | 422, cum detalle campi in `errors` | Non |
| `authentication` | 401 | Non |
| `authorization` | 403 | Non |
| `not_found` | 404 | Non |
| `conflict` | 409 | Interdum |
| `precondition` | 412 | Non |
| `quota` | 402 pro consilio, 413 pro magnitudine | Non |
| `rate_limit` | 429, cum `Retry-After` | Ita |
| `upstream` | 502 aut 504 | Ita |
| `internal` | 500 | Ita |

`request_id` cita cum auxilium petis.

## Retia textoria <!--quire:webhooks-->

In `/admin/webhooks` subscripto, aut per API in
`/webhook_subscriptions`. Elige eventus nomine (`enrolment.created`), per locum
(`enrolment.*`) aut omnes (`*`). Quire primum `webhook.ping` mittit; subscriptio
incipit cum punctum terminale tuum ei respondet.

Traditiones specificationem Standard Webhooks sequuntur:

```
POST /hooks/quire
webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8
webhook-timestamp: 1790000000
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
```

Ut traditionem probes:

1. Stringe `{webhook-id}.{webhook-timestamp}.{raw body}` ex iis ipsis bytis
   acceptis, ante quamquam analysim JSON.
2. HMAC-SHA256 super eo cum arcano subscriptionis tuae computa, et id in
   base64 verte.
3. Cum quoque valore `v1,` in `webhook-signature` tempore constante compara.
   Duo esse possunt durante rotatione arcana; utrumque conveniens est.
4. Tempus signi plus quinque minutis a tuo horologio recusare.

```
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, id, timestamp, rawBody, header) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', Buffer.from(secret.replace(/^whsec_/, ''), 'base64'))
    .update(`${id}.${timestamp}.${rawBody}`).digest();
  return header.split(' ').some((part) => {
    const [version, value] = part.split(',');
    const given = Buffer.from(value ?? '', 'base64');
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
  });
}
```

In `webhook-id` deduplicare: traditio saepius venire potest. Corpus identificatores
et breve summarium portat; rem pro statu eius nunc pete. Traditiones fractae
cum retardatione usque ad 72 horas iterantur, et ex libro traditionis repeti
possunt.

## MCP <!--quire:mcp-->

Servitium MCP Quire in `/mcp` in addressa collegii est, super HTTP fluens.
Client MCP servitium OAuth in `/.well-known/oauth-protected-resource` invenit,
et persona consentit ut in quovis cliente OAuth. Instrumenta ut ea persona agunt,
cum eis potestatibus, et instrumenta destructiva confirmationem poscunt.
Administratores quae instrumenta praesto sint in `/admin/integrations/mcp`
eligunt.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-mcp.webp" alt="The AI assistants page with the server address to give an assistant and a table of the tools it can use." width="944" height="700" loading="lazy" decoding="async"><figcaption>AI assistants (MCP): the server address, and the tools an assistant may call.</figcaption></figure>

## Consilia et API <!--quire:plans-and-the-api-->

Claves API, clientes OAuth, retia textoria et servitium MCP ad ius API consilii
pertinent, et omne consilium standard id continet. In consilio sine eo, creatio
clavis, clientis aut subscriptionis refuitur, scripturae REST et coniunctiones MCP
refuuntur, et lectiones REST pergiunt ut data exportari possint. Refutatio est
documentum problematis cum code `commerce.plan_entitlement`, in categoria
`precondition`.

## Extensiones <!--quire:extensions-->

Genera actuum ipsius Quire, lateres, modi inscriptionis, modi introitus, genera
quaestionum, commentaria, themata et integrationes per eundem registrum
extensionum declarantur cui institutio apud se hospitata addere potest. Extensiones
compilantur: nullus est onerator extensorum in cursu rei, et collegium hospitatum
addere non potest. Administratores quamque extensionem pro collegio suo in
`/admin/extensions` aperit aut claudit (vide [ductionem administratoris](/la/admin/extensions/)).

Ut unam scribas, incipe a lateri et themate exemplari in
`packages/integration/extensions/src/sample.ts`. Punctum extensionis elige et
eius pactum in `points.ts` lege, deinde extensionem cum id, versione, licentia,
eo quod praebet et requirit, et utrum collegium eam claudere liceat declara.
Eam ubi applicatio textoria et operarius componuntur inscribe, ita ut uterque
consentiat. Registrum quaeque regulae puncti ipsius inspicit cum aedificatur et
quotiens `register` vocas, set refuit quae invalida esset cum omne problema
nominatum, et registrum mutatum relinquit cum id facit. Testus ipsius extensionis
debent adserere `extensionContractProblems` pro ea vacuum esse et eius clausuram
id mutare quod afficiat.

Source: https://docs.quirelms.com/la/developer/index.mdx