--- title: "Aratohu mō ngā kaiwhanoke" description: "Te REST API o Quire, te OAuth, ngā webhook, te tūmau MCP me ngā tāpiritanga." image: "https://docs.quirelms.com/og.png" --- > Documentation Index > Fetch the complete documentation index at: https://docs.quirelms.com/mi/llms.txt > Use this file to discover all available pages before exploring further. # Aratohu mō ngā kaiwhanoke Whakamahia te wāhi API o tō rōpū me tētahi tohu whakamanatanga whakarara. Tīmata mai me tētahi tono pānui, tātaritia te whakautu, ā, tiakina ngā mea tūmataiti i waho o te whakahaere waehere me ngā tauira tuhinga. He API tūtahi a Quire: te REST i runga i te HTTPS, e whakaaturia ana e tētahi tuhinga OpenAPI 3.1, me ngā webhook e ia ana tō rātou āhua mō ngā take, me tētahi tūmau MCP mō ngā āwhina AI. Ka tuhia ngā tapae me ngā take katoa i te [tohutoro API](https://docs.quirelms.com/api/). ## Ngā wāhi He wāhi ake ia rōpū, ā, kei raro i a ia te API: ``` https://acme.quirelms.com/api/v1/courses ``` E whakatau ana te tohu whakamanatanga i te rōpū. Ka āraihia tētahi kī mō tētahi rōpū e whakamahia ana i te wāhi o tētahi atu. Ka tukuna te tuhinga OpenAPI i `/api/v1/openapi.json` i te wāhi o ia rōpū, nō reira ka kite ai ngā hanga kaihoko i te āhua e karanga ana koe. ## Whakamanatanga **Ngā kī API** mō ngā pūmanawa me ngā hononga tūmau-ki-tūmau. Ka hanga e tētahi kaiwhakahaere tētahi i te `/admin/integrations/api-keys`, ka kōwhiria ōna rohe, ā, ka kitehia ia kotahi wā. Tukuna ia hei tohu kaiporta: ``` curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50 ``` Ka tīmata ngā kī i `qk_live_` rānei `qk_test_`. Hoatu ia hononga tana ake kī. **OAuth 2.1** mō ngā taupānga e mahi ana i te ingoa o te tāngata hono mai. Rēhitatia tētahi kaihoko i te `/admin/integrations/oauth-clients`, kātia ka whakamahia te ara kōd whakaae me te PKCE (`/oauth/authorize`, `/oauth/token`), rānei ngā tohu whakamanatanga kaihoko mō tētahi kaihoko pūrere. Kei `/.well-known/oauth-authorization-server` te tūhuratanga. Ka whakarara tētahi rohe i te e āea ana e tētahi tohu; kāore e āiahia ia te mahi i te nui atu i te e āea ana e te tāngata. He `resource:read`, `resource:write` me `resource:delete` ngā rohe, hei tauira `courses:read` rānei `enrolments:write`. He whā ngā rohe motuhake, ā, ka whakaaturia me tētahi tohu tūpato i te papa whakaae: `audit:read`, `roles:write`, `tenants:write` me `users:delete`.
The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another.
API keys list who each key acts as and what it may reach.
## Ngā tono - **Ngā whārangi**: ka whakawhāitia ia rārangi ma te pūni. Tukuna te `limit`, kātia te `next_cursor` mai i te `page` hei `cursor` i te wā e tū tonu ana te `has_more` (hei tauira raro). Kāore he toenga. - **Ngā huringa mai i tētahi wā**: ka whakahoki te `updated_since` i te mea kua huri i mua i tētahi wā. Hoatu ia me te `include_deleted=true`, rānei pānui i te `//deletions`, kia mōhio ai i te mea kua tangohia. - **Ngā tohu ā-waho**: ka tuku ia rauemi i tō ake `external_id`, ā, ka pānui rānei tāpiritia te `//ext:{external_id}` i runga i a ia, nō reira kāore e hiahiatia ana i tētahi whakawhiti raraunga te kohinga i ngā tohu o Quire. - **Te ōrite mahi**: tukuna he tohu `Idempotency-Key` i runga i te `POST`, `PATCH` me te `DELETE`. Ka whakahoki tētahi whakamātau anō me te tohu kotahi i te whakautu tuatahi, ehara i te mahi i te mahi rua. E hiahiatia ana tēnei e ngā tapae rōpū. - **Ngā āhua**: kei te ara te āhua matua (`/v1`). I roto i a ia, ka tuhia ia huringa whakararu hei whakāhutanga i te rā, e kōwhiria ana ma te tohu `Quire-Version`, hei tauira `Quire-Version: 2026-09-20`. Mēnā kāore te tohu, ka whiwhi koe i te whakāhutanga e tū ana i te wā i hoatu ai tō tohu whakamanatanga. He whārangi o tētahi rārangi: ``` {"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}} ``` ## Ngā hapa He tuhinga raruraru RFC 9457 ia hapa: ``` {"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..."} ``` Whakarite i runga i te `code`, e tū tonu ana; he tuhinga mō te tangata te `detail`, e āea ana tana whakaaturanga ki a rātou, ā, ka āea ia te huri. Mēnā kāore e mōhio koe i tētahi kōd, kōwhiria te kāwai i runga i te `category`: | Kāwai | Tūmaurunga | Tātari anō | | --- | --- | --- | | `validation` | 422, me ngā kōrero āpure i te `errors` | Kāore | | `authentication` | 401 | Kāore | | `authorization` | 403 | Kāore | | `not_found` | 404 | Kāore | | `conflict` | 409 | I ēhea wā | | `precondition` | 412 | Kāore | | `quota` | 402 mō te pereke, 413 mō te rahi | Kāore | | `rate_limit` | 429, me te `Retry-After` | Āe | | `upstream` | 502 rānei 504 | Āe | | `internal` | 500 | Āe | Tukuna tō `request_id` inā ka whakapā koe ki te tautoko. ## Ngā webhook Rēhitatia i te `/admin/webhooks`, rānei ma te API i te `/webhook_subscriptions`. Kōwhiria ngā take ma tana ingoa (`enrolment.created`), ma te wāhanga (`enrolment.*`) rānei katoa (`*`). Ka tukuna tuatahi a Quire tētahi `webhook.ping`; ka tīmata te kōtuinga i te wā ka whakautu tō tapae i a ia. Ka whai ngā tuku i te whakaritenga Standard Webhooks: ``` POST /hooks/quire webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8 webhook-timestamp: 1790000000 webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= ``` Kia tātaritia tētahi tuku: 1. Hangahia te rārangi `{webhook-id}.{webhook-timestamp}.{raw body}` mai i ngā byte tino tika i whiwhi hia, i mua i te tātari JSON katoa. 2. Tāhau te HMAC-SHA256 i runga i a ia me te kupu tūmataiti o tō kōtuinga, ā, whakawhiti hei base64. 3. Tātaritia me ia uara `v1,` i te `webhook-signature` i te wā ōrite. Ka rua i te wā tāhurihuri o te kupu tūmataiti; e tika ana te ōrite kotahi. 4. Whakakorea ia tohu wā e tū pātai atu i te rima meneti i tō matai poto. ``` 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); }); } ``` Whakakotahitia ma te `webhook-id`: ka taea te tae mai te tuku i ngā wā ruarua. He tohu me tētahi whakatātaki poto kei roto i te tinana; tikina te rauemi mō tana āhua o tēnei wā. Ka whakamātau anō ngā tuku kua rahua me te tatari wā whakanui mō te 72 haora, ā, ka taea te whakahoki i a rātou mai i te rārangi tuku. ## MCP Kei te wāhi o te rōpū te tūmau MCP o Quire i te `/mcp`, ma te HTTP e āea ana te rere. Ka tūhura e tētahi kaihoko MCP te tūmau OAuth mai i `/.well-known/oauth-protected-resource`, ā, ka hono mai te tāngata, ā, ka whakaae i te āhua e mahia ana e tētahi kaihoko OAuth. Ka mahi ngā rākau i te āhua o tērā tāngata, me ōna whakaaetanga, ā, ka pātai ngā rākau muku i te whakaaetanga. E kōwhiria e ngā kaiwhakahaere ēhea ngā rākau e wātea ana i te `/admin/integrations/mcp`.
The AI assistants page with the server address to give an assistant and a table of the tools it can use.
AI assistants (MCP): the server address, and the tools an assistant may call.
## Ngā pereke me te API Kei te tika API o te pereke ngā kī API, ngā kaihoko OAuth, ngā webhook me te tūmau MCP, ā, kei roto ia i ia pereke tūmatanui. I tētahi pereke kāore, ka āraihia te hanga i tētahi kī, kaihoko rānei kōtuinga, ka āraihia hoki ngā tuhi REST me ngā hono MCP, engari ka tū tonu ngā pānui REST, kia noho wātea tonu te raraunga mō te whakakawhaki. He tuhinga raruraru te ārai me te kōd `commerce.plan_entitlement`, i te kāwai `precondition`. ## Ngā tāpiritanga Ka whakaaturia ngā āhua mahi ōna ake o Quire, ngā papa, ngā ara rēhita, ngā ara hono atu, ngā āhua pātai, ngā pūrongo, ngā kākahu me ngā hononga ma te rārangi tāpiritanga kotahi, e āea ana tētahi whakaturanga e whakahaeretia ana e koe te tāpiritanga i a ia. Ka kōmiri ngā tāpiritanga i roto: kāore he kaiutu pūwāea i te wā mahi, ā, kāore e āea ana tētahi rōpū e noho ana i te ratonga tuku te tāpiritanga i tētahi. Ka whakawāhia e ngā kaiwhakahaere ia tāpiritanga mō tō rātou rōpū i te `/admin/extensions` (tirohia te [aratohu kaiwhakahaere](/mi/admin/extensions/)). Kia tuhituhia tētahi, tīmata mai i te papa tauira me te kākahu tauira i te `packages/integration/extensions/src/sample.ts`. Kōwhiria te wāhanga tāpiritanga, ā, pānui i tana konoheni i te `points.ts`, kātia ka tuhia te tāpiritanga me tētahi id, tētahi āhua, tētahi raihana, te e tuku ana me te e hiahiatia ana, me te āea ana tētahi rōpū te whakawāhia i a ia. Rēhitatia ia i te wāhi e hanga ana te taupānga ipurangi me te kai mahi, kia ōrite ai rāua. Ka tātai te rārangi i ā rātou ake ture i te wā e hanga ana ia, ā, ia wā ka karanga koe i te `register`, ka āraihia tētahi kāpui e kore e tika ana, me te kī i ia raruraru, ā, ka noho kore hurihia te rārangi i te wā e mahia ana tēnei. Me tūtohu ngā whakamātau ōna ake o te tāpiritanga, kia kore rārangi te `extensionContractProblems` mō a ia, ā, kia huri te whakawāhia i a ia i te e pā ana ia. Source: https://docs.quirelms.com/mi/developer/index.mdx