--- title: "Giya sa developer" description: "Ang REST API sa Quire, OAuth, webhooks, ang MCP server ug extensions." image: "https://docs.quirelms.com/og.png" --- > Documentation Index > Fetch the complete documentation index at: https://docs.quirelms.com/ceb/llms.txt > Use this file to discover all available pages before exploring further. # Giya sa developer Gamita ang API address sa imong organisasyon ug credential nga may piho nga scope. Sugdi sa read request, susiha ang tubag, ug ibutang ang mga sekreto sa gawas sa source control ug sa mga pananglitan sa dokumentasyon. Usa ra ang public API sa Quire: REST pinaagi sa HTTPS, nga gihulagway sa dokumentong OpenAPI 3.1, uban sa mga webhook nga gipirmahan para sa mga event ug MCP server para sa mga AI assistant. Gilista sa [API reference](https://docs.quirelms.com/api/) ang tanang endpoint ug event. ## Mga address Adunay kaugalingong address ang matag organisasyon, ug anaa didto ang API: ``` https://acme.quirelms.com/api/v1/courses ``` Ang credential maoy motino sa organisasyon. Dili dawaton ang yawe sa usa ka organisasyon kon gamiton kini sa address sa laing organisasyon. Giserbisyo ang dokumentong OpenAPI sa `/api/v1/openapi.json` sa address sa bisan unsang organisasyon, busa kanunayng makita sa mga generator sa client ang bersiyon nga imong gitawag. ## Pag-authenticate **Ang API keys** para sa mga script ug integrasyong server-to-server. Maghimo ang administrador og usa sa `/admin/integrations/api-keys`, mopili sa mga scope niini, ug makakita niini kausa ra. Ipadala kini isip bearer token: ``` curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50 ``` Magsugod ang mga yawe sa `qk_live_` o `qk_test_`. Hatagi og kaugalingong yawe ang matag integration. **Ang OAuth 2.1** para sa mga aplikasyon nga naglihok isip tawo nga naka-sign in. Irehistro ang client sa `/admin/integrations/oauth-clients`, unya gamita ang authorization code flow uban sa PKCE (`/oauth/authorize`, `/oauth/token`), o ang client credentials para sa machine client. Anaa ang discovery sa `/.well-known/oauth-authorization-server`. Gipagamay sa scope ang mahimo sa token; dili gayod kini makahatag og labaw sa mahimo sa tawo. Ang mga scope mao ang `resource:read`, `resource:write` ug `resource:delete`, pananglitan `courses:read` o `enrolments:write`. Adunay upat ka scope nga nanginahanglan og pribilehiyo ug gipakita nga adunay pasidaan sa consent screen: `audit:read`, `roles:write`, `tenants:write` ug `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.
## Mga request - **Pagination**: gigamit sa matag listahan ang cursor pagination. Ipasa ang `limit`, dayon ipasa ang `next_cursor` gikan sa `page` isip `cursor` samtang true ang `has_more` (tan-awa ang pananglitan sa ubos). Walay offset. - **Mga kausaban sukad**: ibalik sa `updated_since` ang mga kausaban human sa usa ka oras. Ipares kini sa `include_deleted=true`, o basaha ang `//deletions`, aron mahibaloan ang mga natangtang. - **Mga eksternal nga identifier**: modawat ang kadaghanan sa mga resource sa kaugalingon nimong `external_id`, ug basahon o i-upsert sa `//ext:{external_id}` pinaagi niini, busa dili kinahanglang tipigan sa sync ang mga identifier sa Quire. - **Idempotency**: ipadala ang header nga `Idempotency-Key` sa `POST`, `PATCH` ug `DELETE`. Kon sulayan pag-usab gamit ang samang yawe, ibalik ang unang tubag imbis nga usbon pag-usab ang datos. Kinahanglan kini sa mga bulk endpoint. - **Mga bersiyon**: anaa sa path ang major version (`/v1`). Sulod niini, petsadong revision ang matag breaking change ug pilion kini gamit ang header nga `Quire-Version`, pananglitan `Quire-Version: 2026-09-20`. Kon walay header, makuha nimo ang revision nga kasamtangan sa dihang giisyu ang credential. Usa ka panid sa listahan: ``` {"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}} ``` ## Mga sayop Ang matag sayop usa ka RFC 9457 problem document: ``` {"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..."} ``` Gamita ang `code` isip basehan kay lig-on kini; para sa mga tawo ang `detail`, luwas kini ipakita kanila, ug mahimong mausab. Kon dili nimo mailhan ang code, gamita ang `category`: | Category | Status | Retry | | --- | --- | --- | | `validation` | 422, nga may detalye sa field sa `errors` | Dili | | `authentication` | 401 | Dili | | `authorization` | 403 | Dili | | `not_found` | 404 | Dili | | `conflict` | 409 | Usahay | | `precondition` | 412 | Dili | | `quota` | 402 para sa plan, 413 para sa gidak-on | Dili | | `rate_limit` | 429, nga may `Retry-After` | Oo | | `upstream` | 502 o 504 | Oo | | `internal` | 500 | Oo | Ihatag ang `request_id` kon mokontak ka sa suporta. ## Webhooks Pag-subscribe sa `/admin/webhooks`, o pinaagi sa API sa `/webhook_subscriptions`. Pilia ang mga event pinaagi sa ngalan (`enrolment.created`), sa bahin (`enrolment.*`) o tanan (`*`). Ipadala una sa Quire ang `webhook.ping`; magsugod ang subscription kon tubagon kini sa imong endpoint. Mosunod ang mga delivery sa espesipikasyon sa Standard Webhooks: ``` POST /hooks/quire webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8 webhook-timestamp: 1790000000 webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= ``` Aron mapamatud-an ang usa ka delivery: 1. Paghimo sa string nga `{webhook-id}.{webhook-timestamp}.{raw body}` gikan sa eksaktong nadawat nga mga byte, sa dili pa mag-parse og JSON. 2. Kwentaha ang HMAC-SHA256 niini gamit ang sekreto sa imong subscription, ug himoa kining base64. 3. Itandi kini sa matag bili nga `v1,` sa `webhook-signature` sa constant time. Mahimong duha kini panahon sa pagtuyok sa sekreto; balido kon motakdo ang bisan hain. 4. Isalikway ang timestamp nga sobra sa lima ka minuto ang kalainan sa imong orasan. ``` 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); }); } ``` Pagsubay sa `webhook-id` aron malikayan ang pagdoble: mahimong madawat ang usa ka delivery kapin sa kausa. Adunay identifier ug mubo nga sumaryo ang body; kuhaa ang resource aron makita ang kasamtangang kahimtang niini. Sulayan pag-usab ang napakyas nga mga delivery nga adunay pagdugang sa gilay-on hangtod 72 oras, ug mahimo kining i-replay gikan sa talaan sa delivery. ## MCP Anaa ang MCP server sa Quire sa `/mcp` sa address sa organisasyon, pinaagi sa streamable HTTP. Makadiskobre ang kliyente sa MCP sa OAuth server gikan sa `/.well-known/oauth-protected-resource`, ug mo-sign in ug mohatag og pagtugot ang tawo sama sa ubang OAuth client. Molihok ang mga tool ubos sa mga permiso sa tawo, ug mangayo og kumpirmasyon ang mga makadaot nga tool. Pilion sa mga administrador ang mga tool nga magamit sa `/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.
## Mga plan ug ang API Kabahin sa API entitlement sa plan ang mga API key, OAuth client, webhook ug MCP server, ug apil kini sa matag standard plan. Sa plan nga walay niini, dili tugotan ang paghimo og key, client o subscription, dili tugotan ang REST write ug koneksiyon sa MCP, apan magpadayon ang REST read aron ma-export ang datos. Problem document ang pagdumili nga adunay code nga `commerce.plan_entitlement`, ubos sa kategoriya nga `precondition`. ## Extensions Ideklara pinaagi sa samang extension registry ang kaugalingong activity type, block, pamaagi sa enrolment, pamaagi sa pag-sign in, tipo sa pangutana, report, tema ug integration sa Quire; makadugang usab niini ang self-hosted nga instalasyon. Nahiusa na ang mga extension sa build: walay runtime plugin loader, ug dili makadugang niini ang organisasyong hosted. I-on o i-off sa mga administrador ang matag extension para sa ilang organisasyon sa `/admin/extensions` (tan-awa ang [giya sa administrador](/ceb/admin/extensions/)). Aron magsulat og extension, sugdi sa sample block ug tema sa `packages/integration/extensions/src/sample.ts`. Pilia ang extension point ug basaha ang kontrata niini sa `points.ts`, unya ideklara ang extension nga adunay id, bersiyon, lisensiya, mga gihatag ug gikinahanglan niini, ug kon puwede kining i-off sa usa ka organisasyon. Irehistro kini diin gihiusa ang web application ug worker aron magkauyon silang duha. Susiha sa registry ang mga lagda sa matag point sa pagtukod niini ug sa matag pagtawag sa `register`; isalikway niini ang set nga dili balido, ipahibalo ang matag problema, ug dili usbon ang registry kon mahitabo kini. Sa kaugalingong mga test sa extension, pamatud-i nga walay sulod ang `extensionContractProblems` para niini ug mausab ang epekto niini kon i-off. Source: https://docs.quirelms.com/ceb/developer/index.mdx