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

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 /<resource>/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 /<resource>/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:

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.

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

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.