---
title: "বিকাশকৰ গাইড"
description: "Quire REST API, OAuth, webhook, MCP server আৰু extension।"
image: "https://docs.quirelms.com/og.png"
---

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

# বিকাশকৰ গাইড

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

আপোনাৰ প্ৰতিষ্ঠানৰ API ঠিকনা আৰু সীমিত scope-ৰ credential ব্যৱহাৰ কৰক। Read request-ৰ পৰা আৰম্ভ কৰি response পৰীক্ষা কৰক আৰু secret source control আৰু documentation-ৰ উদাহৰণৰ বাহিৰত ৰাখক।

Quire-ৰ এটা public API আছে: HTTPS-ৰ ওপৰত REST, OpenAPI 3.1 document-এ বৰ্ণনা কৰে; event-ৰ বাবে signed webhook আৰু AI assistant-ৰ বাবে MCP server আছে। [API তথ্যসূত্ৰ](https://docs.quirelms.com/api/)-ত প্ৰতিটো endpoint আৰু event তালিকাভুক্ত।

## ঠিকনা <!--quire:addresses-->

প্ৰতিটো প্ৰতিষ্ঠানৰ নিজা ঠিকনা থাকে আৰু API ইয়াৰ তলত থাকে:

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

Credential-এ প্ৰতিষ্ঠান নিৰ্ধাৰণ কৰে। এটা প্ৰতিষ্ঠানৰ key আনটোৰ ঠিকনাত ব্যৱহাৰ কৰিলে নাকচ হয়।

যিকোনো প্ৰতিষ্ঠানৰ ঠিকনাত `/api/v1/openapi.json`ত OpenAPI document পোৱা যায়, সেয়ে client generator-এ আপুনি call কৰা version-টো সদায় দেখে।

## প্ৰমাণীকৰণ <!--quire:authentication-->

**API key** script আৰু server-to-server integration-ৰ বাবে। প্ৰশাসকে `/admin/integrations/api-keys`ত এটা সৃষ্টি কৰি scope বাছি এবাৰ দেখে। Bearer token হিচাপে পঠিয়াওক:

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

Key `qk_live_` বা `qk_test_`ৰে আৰম্ভ হয়। প্ৰতিটো integration-ৰ নিজা key দিয়ক।

**OAuth 2.1** ছাইন-ইন কৰা ব্যক্তিৰ হৈ কাম কৰা application-ৰ বাবে। `/admin/integrations/oauth-clients`ত client register কৰি PKCE (`/oauth/authorize`, `/oauth/token`)-সহ authorization code flow, অথবা machine client-ৰ বাবে client credentials ব্যৱহাৰ কৰক। Discovery `/.well-known/oauth-authorization-server`ত। Scope-এ token-এ কি কৰিব পাৰে সংকুচিত কৰে; ব্যক্তিজনে কৰিব পৰাতকৈ অধিক কৰিব নিদিয়ে।

Scope-সমূহ `resource:read`, `resource:write` আৰু `resource:delete`, যেনে `courses:read` বা `enrolments:write`। চাৰিটা privileged আৰু consent screen-ত সতৰ্কবাণীসহ দেখুওৱা হয়: `audit:read`, `roles:write`, `tenants:write` আৰু `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>

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

- **Pagination**: প্ৰতিটো list cursor pagination-যুক্ত। `limit` দিয়ক, তাৰ পিছত `next_cursor` থকা `page`ৰ পৰা `cursor` হিচাপে পঠিয়াওক, `has_more` true থকালৈ (তলৰ উদাহৰণ)। Offset নাই।
- **ইয়াৰ পিছৰ পৰিৱৰ্তন**: `updated_since`-এ এটা সময়ৰ পিছত সলনি হোৱা বস্তু দিয়ে। মচা বস্তু জানিবলৈ `include_deleted=true` যোগ কৰক, অথবা `/<resource>/deletions` পঢ়ক।
- **External identifier**: বেছিভাগ resource-এ আপোনাৰ `external_id` গ্ৰহণ কৰে; `/<resource>/ext:{external_id}`-এ তাৰ অনুসৰি পঢ়ে বা upsert কৰে, যাতে sync-ত Quire identifier ৰাখিব নালাগে।
- **Idempotency**: `Idempotency-Key` header `POST`, `PATCH` আৰু `DELETE` request-ত পঠিয়াওক। একে key-ৰে retry কৰিলে কাম দুবাৰ নকৰি প্ৰথম response ঘূৰাই দিয়ে। Bulk endpoint-ত এইটো বাধ্যতামূলক।
- **Version**: Major version path-ত (`/v1`) থাকে। ইয়াৰ ভিতৰত backward incompatible প্ৰতিটো পৰিৱৰ্তন তাৰিখযুক্ত revision; `Quire-Version` header-ৰে বাছক, যেনে `Quire-Version: 2026-09-20`। Header নিদিলে credential জাৰি কৰাৰ সময়ৰ revision পাব।

List-ৰ এটা page:

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

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

প্ৰতিটো error 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..."}
```

স্থিতিশীল `code` অনুসৰি branch কৰক; `detail` মানুহৰ বাবে লিখা, দেখুৱাবলৈ নিৰাপদ আৰু সলনি হ’ব পাৰে। Code চিনিব নোৱাৰিলে `category` অনুসৰি ভাগ কৰক:

| Category | Status | Retry |
| --- | --- | --- |
| `validation` | 422, `errors`ত field detail-সহ | নহয় |
| `authentication` | 401 | নহয় |
| `authorization` | 403 | নহয় |
| `not_found` | 404 | নহয় |
| `conflict` | 409 | কেতিয়াবা |
| `precondition` | 412 | নহয় |
| `quota` | plan-ৰ বাবে 402, size-ৰ বাবে 413 | নহয় |
| `rate_limit` | 429, `Retry-After`-সহ | হয় |
| `upstream` | 502 বা 504 | হয় |
| `internal` | 500 | হয় |

Support-ৰ সৈতে যোগাযোগ কৰোঁতে `request_id` উল্লেখ কৰক।

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

`/admin/webhooks`ত অথবা API-ৰ `/webhook_subscriptions`ত subscribe কৰক। Event নাম অনুসৰি (`enrolment.created`), এলেকা অনুসৰি (`enrolment.*`) বা সকলো (`*`) বাছক। Quire-এ প্ৰথমে `webhook.ping` পঠিয়ায়; আপোনাৰ endpoint-এ উত্তৰ দিলেহে subscription আৰম্ভ হয়।

Delivery-সমূহে Standard Webhooks specification অনুসৰণ কৰে:

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

Delivery verify কৰিবলৈ:

1. JSON parse কৰাৰ আগতে পোৱা হুবহু byte-ৰে `{webhook-id}.{webhook-timestamp}.{raw body}` string বনাওক।
2. Subscription secret-ৰে ইয়াৰ ওপৰত HMAC-SHA256 গণনা কৰি base64 কৰক।
3. প্ৰতিটো `v1,` value-ৰ সৈতে `webhook-signature`ৰ value constant time-ত তুলনা কৰক। Secret rotation-ত দুটা থাকিব পাৰে; যিকোনো এটা মিলা মান্য।
4. আপোনাৰ clock-ৰ পৰা পাঁচ মিনিটতকৈ বেছি আঁতৰি থকা timestamp নাকচ কৰক।

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

`webhook-id` অনুসৰি duplicate আঁতৰাওক: delivery এবাৰতকৈ অধিক আহিব পাৰে। Body-ত identifier আৰু চুটি সাৰাংশ থাকে; বৰ্তমান অৱস্থাৰ বাবে resource fetch কৰক। বিফল delivery-ৰ 72 ঘণ্টালৈকে backoff-সহ retry হয় আৰু delivery log-ৰ পৰা replay কৰিব পাৰি।

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

Quire-ৰ MCP server প্ৰতিষ্ঠানৰ ঠিকনাৰ `/mcp`ত streamable HTTP-ৰে থাকে। MCP client-এ `/.well-known/oauth-protected-resource`ৰ পৰা OAuth server বিচাৰে; যিকোনো OAuth client-ৰ দৰে ব্যক্তিয়ে sign in কৰি consent দিয়ে। Tool-সমূহ ব্যক্তিজনৰ permission-সহ চলে আৰু ধ্বংসাত্মক tool-এ নিশ্চিতকৰণ বিচাৰে। প্ৰশাসকে `/admin/integrations/mcp`ত উপলব্ধ tool বাছে।

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

## Plan আৰু API <!--quire:plans-and-the-api-->

API key, OAuth client, webhook আৰু MCP server plan-ৰ API entitlement-ৰ অন্তৰ্গত; প্ৰতিটো standard plan-ত ই থাকে। নথকা plan-ত key, client বা subscription সৃষ্টি নাকচ হয়, REST write আৰু MCP connection নাকচ হয়; data export কৰিব পৰা থাকিবলৈ REST read চলি থাকে। নাকচটো `commerce.plan_entitlement` code থকা `precondition` category-ৰ problem document।

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

Quire-ৰ নিজৰ activity type, block, enrolment method, sign-in method, question type, report, theme আৰু integration-সমূহ self-hosted installation-এ যোগ কৰিব পৰা একেটা extension registry-ৰ জৰিয়তে ঘোষণা হয়। Extension compile কৰি অন্তৰ্ভুক্ত কৰা হয়: runtime plugin loader নাই, hosted প্ৰতিষ্ঠানে যোগ কৰিব নোৱাৰে। প্ৰশাসকে `/admin/extensions`ত নিজৰ প্ৰতিষ্ঠানৰ বাবে প্ৰতিটো extension on বা off কৰে (চাওক [প্ৰশাসকৰ গাইড](/as/admin/extensions/))।

এটা লিখিবলৈ `packages/integration/extensions/src/sample.ts`ৰ sample block আৰু theme-ৰ পৰা আৰম্ভ কৰক। Extension point বাছি `points.ts`ৰ contract পঢ়ক; তাৰ পিছত ID, version, licence, কি দিয়ে আৰু লাগে, লগতে প্ৰতিষ্ঠানে off কৰিব পাৰেনে, এইবোৰসহ extension ঘোষণা কৰক। Web application আৰু worker একেলগ কৰা ঠাইত register কৰক, যাতে দুয়ো একমত হয়। Build কৰাৰ সময়ত আৰু প্ৰতিবাৰ `register` call-ত registry-এ point-ৰ নিয়ম পৰীক্ষা কৰে; সমস্যা নামসহ অবৈধ set নাকচ কৰে আৰু নাকচ কৰিলে registry সলনি নকৰে। Extension-ৰ নিজৰ test-এ ইয়াৰ বাবে `extensionContractProblems` খালী আৰু off কৰিলে ইয়াৰ প্ৰভাৱিত বস্তু সলনি হোৱা নিশ্চিত কৰিব লাগে।

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