---
title: "Ntuziaka onye mmepụta"
description: "REST API Quire, OAuth, webhooks, sava MCP na extensions."
image: "https://docs.quirelms.com/og.png"
---

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

# Ntuziaka onye mmepụta

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

Jiri adreesị API otu gị na nzere nwere oke. Bido na arịrịọ ọgụgụ, lelee
nzaghachi, debekwa nzuzo n'èzí njikwa isi mmalite na ihe atụ akwụkwọ.

Quire nwere otu API ọha: REST site na HTTPS, nke akwụkwọ OpenAPI 3.1 kọwara,
na webhook e binyere aka maka ihe omume na sava MCP maka ndị enyemaka AI.
[Ntụaka API](https://docs.quirelms.com/api/) na-edepụta endpoint na ihe omume ọ bụla.

## Adreesị <!--quire:addresses-->

Otu ọ bụla nwere adreesị nke ya, API bi n'okpuru ya:

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

Nzere na-ekpebi otu. A jụrụ igodo nke otu e ji na adreesị nke ọzọ.

A na-enye akwụkwọ OpenAPI na `/api/v1/openapi.json` na adreesị otu ọ bụla, ka
ndị na-emepụta client na-ahụ ụdị ị na-akpọ mgbe niile.

## Nyocha njirimara <!--quire:authentication-->

**Igodo API** bụ maka scripts na njikọta sava na sava. Onye nchịkwa
na-emepụta otu na `/admin/integrations/api-keys`, na-ahọrọ scopes ya, ma
na-ahụ ya otu ugboro. Ziga ya dịka token bearer:

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

Igodo na-amalite na `qk_live_` ma ọ bụ `qk_test_`. Nye njikọta ọ bụla igodo
nke ya.

**OAuth 2.1** bụ maka ngwa na-eme ihe dịka onye banyere. Debanye client na
`/admin/integrations/oauth-clients`, emesịa jiri authorization code flow na
PKCE (`/oauth/authorize`, `/oauth/token`), ma ọ bụ nzere client maka client
igwe. Nchọpụta dị na `/.well-known/oauth-authorization-server`. Scope
na-ebelata ihe token nwere ike ime; ọ dịghị mgbe ọ na-ahapụ ya ime karịa
ihe onye ahụ nwere ike.

Scopes bụ `resource:read`, `resource:write` na `resource:delete`, dịka
`courses:read` ma ọ bụ `enrolments:write`. Anọ nwere ikike pụrụ iche ma
na-egosi na ịdọ aka ná ntị na ihuenyo nkwenye: `audit:read`, `roles:write`,
`tenants:write` na `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>

## Arịrịọ <!--quire:requests-->

- **Pagination**: ndepụta ọ bụla bụ cursor paginated. Nyefee `limit`,
  emesịa `next_cursor` site na `page` dịka `cursor` mgbe `has_more` bụ
  eziokwu (ihe atụ n'okpuru). Enweghị offset.
- **Mgbanwe kemgbe**: `updated_since` na-alaghachi ihe gbanwere mgbe oge.
  Jikọọ ya na `include_deleted=true`, ma ọ bụ gụọ
  `/<resource>/deletions`, ka ịmata ihe e wepụrụ.
- **Nchọpụta mpụga**: ọtụtụ akụ na-anabata `external_id` nke gị, na
  `/<resource>/ext:{external_id}` na-agụ ma ọ bụ upserts site na ya, ka
  mmekọrịta ghara ịchọ ịchekwa nchọpụta Quire.
- **Idempotency**: ziga nkụnye `Idempotency-Key` na `POST`, `PATCH` na
  `DELETE`. Mgbalị ọzọ na otu igodo na-alaghachi nzaghachi mbụ kama ịrụ
  ọrụ ugboro abụọ. Endpoints bulk chọrọ ya.
- **Ụdị**: ụdị ukwu dị na ụzọ (`/v1`). N'ime ya, mgbanwe na-emebi ọ bụla bụ
  revision nwere ụbọchị, a na-ahọrọ na nkụnye `Quire-Version`, dịka
  `Quire-Version: 2026-09-20`. Na-enweghị nkụnye ị na-enweta revision dị
  ugbu a mgbe e nyere nzere gị.

Peeji nke ndepụta:

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

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

Njehie ọ bụla bụ akwụkwọ nsogbu RFC 9457:

```
{"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..."}
```

Alaka na `code`, nke kwụsiri ike; e dere `detail` maka mmadụ, ọ dị nchebe
igosi ha, ọ nwekwara ike ịgbanwe. Mgbe ị mataghị koodu, tinye na
`category`:

| Otu | Ọnọdụ | Mgbalị ọzọ |
| --- | --- | --- |
| `validation` | 422, na nkọwa ubi na `errors` | Mba |
| `authentication` | 401 | Mba |
| `authorization` | 403 | Mba |
| `not_found` | 404 | Mba |
| `conflict` | 409 | Mgbe ụfọdụ |
| `precondition` | 412 | Mba |
| `quota` | 402 maka atụmatụ, 413 maka nha | Mba |
| `rate_limit` | 429, na `Retry-After` | Ee |
| `upstream` | 502 ma ọ bụ 504 | Ee |
| `internal` | 500 | Ee |

Kwuo `request_id` mgbe ị kpọtụrụ nkwado.

## Webhooks <!--quire:webhooks-->

Denye aha na `/admin/webhooks`, ma ọ bụ site na API na
`/webhook_subscriptions`. Họrọ ihe omume site n'aha
(`enrolment.created`), site na mpaghara (`enrolment.*`) ma ọ bụ niile
(`*`). Quire na-eziga `webhook.ping` nke mbụ; ndenye aha na-amalite ozugbo
endpoint gị zara ya.

Nnyefe na-agbaso nkọwa Standard Webhooks:

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

Iji nyochaa nnyefe:

1. Wuo eriri `{webhook-id}.{webhook-timestamp}.{raw body}` site na bytes
   kpọmkwem anatara, tupu nyocha JSON ọ bụla.
2. Gbakọọ HMAC-SHA256 n'elu ya na nzuzo ndenye aha gị, mee ya base64.
3. Tụnyere na uru `v1,` ọ bụla na `webhook-signature` n'oge na-adịgide.
   Abụọ nwere ike ịdị n'oge ntụgharị nzuzo; nke ọ bụla dabara dị irè.
4. Jụ timestamp karịrị nkeji ise site na elekere gị.

```
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);
  });
}
```

Wepụ oyiri na `webhook-id`: nnyefe nwere ike ịbịarute karịa otu ugboro. Ahụ
na-ebu nchọpụta na nchịkọta mkpụmkpụ; weta akụ maka ọnọdụ ya ugbu a. A
na-anwale nnyefe dara ọzọ na backoff ruo awa 72, a pụkwara ịkpọghachi ha
site na ndekọ nnyefe.

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

Sava MCP Quire dị na `/mcp` na adreesị otu, site na HTTP a ga-ebugharị.
Client MCP na-achọpụta sava OAuth site na
`/.well-known/oauth-protected-resource`, onye ahụ na-abanye ma kweta dịka
client OAuth ọ bụla. Ngwa na-eme ihe dịka onye ahụ, na ikike ha, ngwa
na-emebi emebi na-arịọ nkwenye. Ndị nchịkwa na-ahọrọ ngwa dị na
`/admin/integrations/mcp`.

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

## Atụmatụ na API <!--quire:plans-and-the-api-->

Igodo API, clients OAuth, webhooks na sava MCP bụ nke ikike API atụmatụ,
atụmatụ ọkọlọtọ ọ bụla gụnyere ya. Na atụmatụ na-enweghị ya, a jụrụ
imepụta igodo, client ma ọ bụ ndenye aha, a jụrụ ederede REST na njikọ MCP,
ọgụgụ REST na-aga n'ihu ka data wee nọgide na-ebupụ. Ọjụjụ bụ akwụkwọ
nsogbu na koodu `commerce.plan_entitlement`, na otu `precondition`.

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

A na-akpọsa ụdị ọrụ Quire, blocks, ụzọ ndebanye aha, ụzọ nbanye, ụdị
ajụjụ, akụkọ, themes na njikọta site n'otu ndekọ extension nke nrụnye a
na-elekọta n'onwe ya nwere ike itinye na ya. A na-achịkọta Extensions n'ime:
enweghị loader plugin runtime, otu a na-elekọta enweghị ike itinye otu. Ndị
nchịkwa na-agbanye extension ọ bụla ma ọ bụ gbanyụọ maka otu ha na
`/admin/extensions` (lee [ntuziaka onye nchịkwa](/ig/admin/extensions/)).

Iji dee otu, bido na block ihe atụ na theme na
`packages/integration/extensions/src/sample.ts`. Họrọ ebe extension wee gụọ
contract ya na `points.ts`, emesịa kpọsaa extension na id, ụdị, licence, ihe
ọ na-enye ma chọọ, na ma otu nwere ike ịgbanyụ ya. Debanye ya ebe a na-ahazi
ngwa weebụ na worker, ka ha abụọ kwekọrịta. Ndekọ na-enyocha iwu nke ebe
ọ bụla mgbe e wuru ya na mgbe ọ bụla ị kpọrọ `register`, na-ajụ otu
na-agaghị adị irè na nsogbu ọ bụla akpọrọ, wee hapụ ndekọ na-agbanweghị
mgbe o mere ya. Ule extension kwesịrị ikwenye na
`extensionContractProblems` tọgbọ chakoo maka ya na na ịgbanyụ ya na-agbanwe
ihe ọ na-emetụta.

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