# REST API


# REST API

ഓരോ imatic ഉൽപ്പന്നവും നിങ്ങളുടെ സ്വന്തം കോഡിൽ നിന്ന് ഓട്ടോമേറ്റ് ചെയ്യാവുന്ന REST API-കൾ നൽകുന്നു. ഈ പേജിലെ കൺവെൻഷനുകൾ — നിങ്ങൾ എങ്ങനെ ഓതന്റിക്കേറ്റ് ചെയ്യുന്നു, API കീകൾ എങ്ങനെ പ്രവർത്തിക്കുന്നു, webhooks എങ്ങനെ സൈൻ ചെയ്യപ്പെടുന്നു, പേജിനേഷൻ, റേറ്റ് ലിമിറ്റുകൾ, എററുകൾ എങ്ങനെ പെരുമാറുന്നു — ഉൽപ്പന്നങ്ങളിലുടനീളം ഒരുപോലെയാണ്. വ്യത്യാസപ്പെടുന്നത് URL-ന്റെ രൂപവും ഓരോ ഉൽപ്പന്നവും വെളിപ്പെടുത്തുന്ന **റിസോഴ്സുകളും** ആണ്: Calendar വേർഷൻ ചെയ്ത `/v1` പാതകൾ ഉപയോഗിക്കുന്നു, Survey ക്രിയാ-ശൈലിയിലുള്ള `POST` എൻഡ്പോയിന്റുകൾ ഉപയോഗിക്കുന്നു. ഓരോ ഉൽപ്പന്നത്തിന്റെയും ഡെവലപ്പർ പേജ് അതിന്റെ കൃത്യമായ സർഫേസ് രേഖപ്പെടുത്തുന്നു.

:::note[ഉദാഹരണങ്ങൾ വിശദീകരണാത്മകം മാത്രമാണ്]

താഴെയുള്ള റിക്വസ്റ്റ്, റെസ്പോൺസ് സ്നിപ്പെറ്റുകൾ കോളുകളുടെ *രൂപം* കാണിക്കുന്നു — ഹെഡറുകൾ, ഓത്ത്, എറർ എൻവലപ്പുകൾ — കൃത്യമായ ഫീൽഡ്-ബൈ-ഫീൽഡ് സ്കീമയല്ല. ഒരു ഉൽപ്പന്നത്തിന്റെ കൃത്യമായ എൻഡ്പോയിന്റുകൾ, പാരാമീറ്ററുകൾ, ഫീൽഡ് നാമങ്ങൾ എന്നിവയ്ക്ക്, ആ ഉൽപ്പന്നത്തിന്റെ ഡെവലപ്പർ പേജിലേക്കുള്ള ലിങ്കുകൾ പിന്തുടരുക.

:::

## ഓതന്റിക്കേഷൻ

imatic രണ്ട് വ്യത്യസ്ത കോളർമാർക്കായി രണ്ട് തരം ക്രെഡൻഷ്യലുകൾ ഉപയോഗിക്കുന്നു:

- **JWT (സെഷൻ ടോക്കൺ)** — നിങ്ങൾ ഇമെയിലും പാസ്‌വേഡും ഉപയോഗിച്ച് സൈൻ ഇൻ ചെയ്തതിന് ശേഷം വെബ് ആപ്പ് ഉപയോഗിക്കുന്നത്. ഇത് ബ്രൗസറിൽ *നിങ്ങളെ* പ്രതിനിധീകരിക്കുന്നു, ഹ്രസ്വകാലമാണ്. നിങ്ങൾ ഇത് നേരിട്ട് കൈകാര്യം ചെയ്യുന്നില്ല; ആപ്പാണ് അത് ചെയ്യുന്നത്.
- **സ്കോപ്പ്ഡ് API കീ** — *നിങ്ങളുടെ കോഡ്* `v1` REST API കോൾ ചെയ്യാൻ ഉപയോഗിക്കുന്നത്. നിങ്ങൾ തന്നെ അത് സൃഷ്ടിക്കുന്നു, അത് വ്യക്തമായ സ്കോപ്പുകൾ വഹിക്കുന്നു, ഒരു ബ്രൗസർ സെഷനോടൊപ്പം അത് കാലഹരണപ്പെടുന്നില്ല.

സെർവർ-ടു-സെർവർ കോളുകൾക്ക്, എപ്പോഴും ഒരു API കീ ഉപയോഗിക്കുക — ഒരിക്കലും നിങ്ങളുടെ പാസ്‌വേഡോ പകർത്തിയ സെഷൻ ടോക്കണോ അല്ല.

### ഒരു API കീ അയയ്ക്കുന്നു

`Authorization` ഹെഡറിൽ കീ ഒരു Bearer ടോക്കണായി കൈമാറുക:

```bash
curl https://<product-host>/v1/event-types \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial" \
  -H "Content-Type: application/json"
```

## API കീകൾ എങ്ങനെ പ്രവർത്തിക്കുന്നു

ഓരോ ഉൽപ്പന്നത്തിന്റെയും ഡെവലപ്പർ ഏരിയയിൽ നിങ്ങൾ API കീകൾ സൃഷ്ടിക്കുകയും കൈകാര്യം ചെയ്യുകയും ചെയ്യുന്നു — ഉദാഹരണത്തിന് Calendar-ന്റെ **Developers → API keys**, Survey-യുടെ **Developers → API keys**. ഒരു കീക്ക് മനസ്സിലാക്കാൻ വിലയുള്ള മൂന്ന് സവിശേഷതകളുണ്ട്:

- **`prefix.secret` ഫോർമാറ്റ്** — ഒരു കീക്ക് ഒരു പൊതുവായ **prefix**-ഉം ഒരു സീക്രട്ട് ഭാഗവുമുണ്ട്, ഒരു ഡോട്ട് കൊണ്ട് ചേർത്തിരിക്കുന്നു (ഉദാഹരണത്തിന് `cal_abc123.s3cr3t_keymaterial` — Calendar കീകൾ ഒരു ചെറിയ `cal_` prefix ഉപയോഗിക്കുന്നു). ലിസ്റ്റുകളിലും ലോഗുകളിലും കീ തിരിച്ചറിയാൻ prefix imatic-നെ അനുവദിക്കുന്നു; സീക്രട്ട് അത് നിങ്ങളുടേതാണെന്ന് തെളിയിക്കുന്നു.
- **ഒരിക്കൽ മാത്രം കാണിക്കുന്നു** — കീയുടെ പൂർണ്ണ മൂല്യം നിങ്ങൾ അത് സൃഷ്ടിക്കുന്ന നിമിഷത്തിൽ മാത്രമേ പ്രദർശിപ്പിക്കൂ. അതിന് ശേഷം, prefix മാത്രമേ ദൃശ്യമാകൂ.
- **സ്കോപ്പുകൾ** — ഓരോ കീയും നിങ്ങൾ അനുവദിക്കുന്ന പ്രവർത്തനങ്ങളിലേക്ക് പരിമിതപ്പെടുത്തിയിരിക്കുന്നു. Calendar-ന്റെ സ്കോപ്പുകൾ `slots:read`, `bookings:read`, `bookings:write`, `mcp` എന്നിവയാണ് (`mcp` സ്കോപ്പ് ആണ് ഒരു AI ഏജന്റിന്റെ കീക്ക് ആവശ്യമുള്ളത് — [AI ഏജന്റുകൾക്കായുള്ള MCP](./mcp) കാണുക). ഒരു കീയുടെ സ്കോപ്പ് കവിയുന്ന ഒരു റിക്വസ്റ്റ് നിരസിക്കപ്പെടുന്നു.

:::danger[API കീകളെ പാസ്‌വേഡുകൾ പോലെ കണക്കാക്കുക]

ഒരു കീയുടെ സീക്രട്ട് സൃഷ്ടിക്കുമ്പോൾ ഒരിക്കൽ മാത്രമേ കാണിക്കൂ. അപ്പോൾ അത് പകർത്തി ഒരു സീക്രട്ട് മാനേജറിലോ എൻവയോൺമെന്റ് വേരിയബിളിലോ സൂക്ഷിക്കുക — ഒരിക്കലും സോഴ്സ് കൺട്രോളിലോ, ഒരു സ്ക്രീൻഷോട്ടിലോ, പങ്കിട്ട ഡോക്കിലോ അല്ല. ഒരു കീ വെളിപ്പെട്ടാൽ, ഡെവലപ്പർ ഏരിയയിൽ അത് **revoke ചെയ്യുക** എന്നിട്ട് ഒരു പകരം സൃഷ്ടിക്കുക. Revocation ഉടനടി പ്രാബല്യത്തിൽ വരുന്നു.

:::

## Webhooks

മാറ്റങ്ങൾക്കായി പോൾ ചെയ്യുന്നതിന് പകരം, ഒരു webhook URL രജിസ്റ്റർ ചെയ്യുക, എന്തെങ്കിലും സംഭവിക്കുമ്പോൾ imatic അതിലേക്ക് ഒരു ഇവന്റ് `POST` ചെയ്യും — ഉദാഹരണത്തിന് Calendar-ൽ ഒരു ബുക്കിംഗ് സൃഷ്ടിക്കപ്പെടുമ്പോൾ അല്ലെങ്കിൽ Survey-യിൽ ഒരു റെസ്പോൺസ് സമർപ്പിക്കുമ്പോൾ. ഓരോ ഉൽപ്പന്നത്തിന്റെയും **Developers → Webhooks** ഏരിയയിൽ നിങ്ങൾ webhook എൻഡ്പോയിന്റുകൾ കൈകാര്യം ചെയ്യുന്നു, അവിടെ നിങ്ങൾക്ക് ഒരു ടെസ്റ്റ് ഡെലിവറിയും അയയ്ക്കാം.

ഒരു ഡെലിവറി ഏകദേശം ഇതുപോലെ കാണപ്പെടുന്നു:

```http
POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
X-Imatic-Signature: t=1718900000,v1=9f86d081884c7d659a2feaa0c55ad015...

{
  "event": "booking.created",
  "data": { "...": "event-specific payload" }
}
```

### സിഗ്നേച്ചർ പരിശോധിക്കുന്നു

ഓരോ ഡെലിവറിയും നിങ്ങളുടെ എൻഡ്പോയിന്റിന്റെ സൈനിംഗ് സീക്രട്ട് ഉപയോഗിച്ച് **HMAC-SHA256** കൊണ്ട് സൈൻ ചെയ്യപ്പെടുന്നു, ഒരു Stripe-ശൈലിയിലുള്ള `X-Imatic-Signature` ഹെഡറിൽ. ഹെഡർ രണ്ട് ഫീൽഡുകൾ വഹിക്കുന്നു: `t`, അയയ്ക്കുന്ന സമയത്തെ unix-epoch **സെക്കൻഡുകൾ**, പിന്നെ `v1`, `${t}.${body}` എന്ന സ്ട്രിങ്ങിന്റെ ഹെക്സ് HMAC (ടൈംസ്റ്റാമ്പ്, ഒരു ലിറ്ററൽ ഡോട്ട്, പിന്നെ കൃത്യമായ റോ റിക്വസ്റ്റ് ബോഡി). പരിശോധിക്കാൻ, ഹെഡർ വിഭജിക്കുക, നിങ്ങളുടെ സൈനിംഗ് സീക്രട്ട് ഉപയോഗിച്ച് `t + "." + rawBody`-ന് മേൽ `v1` വീണ്ടും കണക്കാക്കുക, constant-time-ൽ താരതമ്യം ചെയ്യുക. പൊരുത്തപ്പെടുന്നില്ലെങ്കിൽ നിരസിക്കുക — replay-നെതിരെ കാക്കാൻ `t` കുറച്ച് മിനിറ്റുകളിൽ പഴയതാണെങ്കിൽ ഓപ്ഷണലായി നിരസിക്കുകയും ചെയ്യാം.

```js
import crypto from "node:crypto";

function isValid(rawBody, signatureHeader, signingSecret) {
  // Header shape: "t=<epoch-seconds>,v1=<hex hmac>"
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("=")),
  );
  const { t, v1 } = parts;
  if (!t || !v1) return false;

  // Sign the timestamped body: `${t}.${rawBody}` — NOT the raw body alone.
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // Constant-time comparison to avoid timing attacks.
  const a = Buffer.from(v1);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```

:::note[ഉൽപ്പന്നം അനുസരിച്ച് കൃത്യമായ സ്കീം]

മുകളിലുള്ള `t=…,v1=…` സ്കീം Calendar-ന്റേതാണ്. ഒരു verifier ഷിപ്പ് ചെയ്യുന്നതിന് മുമ്പ് ഓരോ ഉൽപ്പന്നത്തിന്റെയും ഡെവലപ്പർ പേജിൽ ഹെഡർ നാമം, ഫീൽഡുകൾ, സൈൻ ചെയ്ത സ്ട്രിങ് എന്നിവ സ്ഥിരീകരിക്കുക.

:::

:::tip[വേഗത്തിൽ പ്രതികരിക്കുക, പിന്നീട് പ്രോസസ് ചെയ്യുക]

രസീത് സ്ഥിരീകരിക്കാൻ വേഗത്തിൽ ഒരു `2xx` തിരികെ നൽകുക, എന്നിട്ട് ഏതെങ്കിലും മന്ദഗതിയിലുള്ള ജോലി അസിൻക്രണസായി ചെയ്യുക. നിങ്ങളുടെ എൻഡ്പോയിന്റ് മന്ദഗതിയിലാണെങ്കിലോ എറർ ചെയ്താലോ, ഡെലിവറികൾ വീണ്ടും ശ്രമിച്ചേക്കാം.

:::

## പേജിനേഷൻ

ലിസ്റ്റ് എൻഡ്പോയിന്റുകൾ ഫലങ്ങൾ പേജുകളായി തിരികെ നൽകുന്നു, അതിനാൽ ഒരൊറ്റ കോളിന് ഒരിക്കലും എല്ലാം ലോഡ് ചെയ്യേണ്ടി വരുന്നില്ല. റിക്വസ്റ്റിൽ പേജിംഗ് പാരാമീറ്ററുകൾ കൈമാറുക, അടുത്ത പേജ് ലഭിക്കാൻ റെസ്പോൺസിലെ പേജിംഗ് മെറ്റാഡാറ്റ വായിക്കുക.

```bash
curl "https://<product-host>/v1/bookings?limit=25" \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial"
```

```json
{
  "success": true,
  "data": [ { "...": "one item per result" } ],
  "pagination": { "page": 1, "limit": 20, "total": 0, "pages": 0 }
}
```

കൂടുതൽ ഫലങ്ങൾ ഇല്ലാതാകുന്നതുവരെ അടുത്ത പേജ് അഭ്യർത്ഥിക്കുന്നത് തുടരുക.

## റേറ്റ് ലിമിറ്റിംഗ്

പ്ലാറ്റ്ഫോം ന്യായവും സ്ഥിരവുമായി നിലനിർത്താൻ API കീകൾ റേറ്റ് ലിമിറ്റ് ചെയ്യപ്പെടുന്നു. നിങ്ങൾ ലിമിറ്റ് കവിഞ്ഞാൽ, API HTTP `429 Too Many Requests` പ്രതികരണം നൽകുന്നു. എൻഡ്പോയിന്റ് ഇടിച്ചുകൊണ്ടിരിക്കുന്നതിന് പകരം — ആദർശപരമായി എക്സ്പോണൻഷ്യൽ ബാക്ക്ഓഫും ജിറ്ററും ഉപയോഗിച്ച് — ബാക്ക് ഓഫ് ചെയ്ത് വീണ്ടും ശ്രമിക്കുക.

```json
{
  "success": false,
  "error": "rate_limited",
  "message": "Too many requests. Please retry after a short delay."
}
```

## എറർ കൈകാര്യം

എന്താണ് തെറ്റിയതെന്ന് വിവരിക്കുന്ന ഒരു JSON ബോഡിയോടെ എററുകൾ സ്റ്റാൻഡേർഡ് HTTP സ്റ്റാറ്റസ് കോഡുകൾ ഉപയോഗിക്കുന്നു. നിങ്ങൾ ഏറ്റവും കൂടുതൽ കാണുന്ന കോഡുകൾ:

- **`400`** — റിക്വസ്റ്റ് രൂപഭംഗം വന്നതോ വാലിഡേഷൻ പരാജയപ്പെട്ടതോ ആയിരുന്നു.
- **`401`** — കാണാത്ത അല്ലെങ്കിൽ അസാധുവായ API കീ.
- **`403`** — കീ സാധുവാണ് പക്ഷേ ഈ പ്രവർത്തനത്തിനുള്ള സ്കോപ്പ് (അല്ലെങ്കിൽ org ആക്സസ്) ഇല്ല.
- **`404`** — റിസോഴ്സ് നിലവിലില്ല അല്ലെങ്കിൽ ഈ കീക്ക് ദൃശ്യമല്ല.
- **`409`** — ഒരു വൈരുദ്ധ്യം, ഉദാഹരണത്തിന് ഇപ്പോൾ എടുത്ത ഒരു സ്ലോട്ട് ബുക്ക് ചെയ്യാൻ ശ്രമിക്കുന്നത്.
- **`429`** — റേറ്റ് ലിമിറ്റ് ചെയ്തു; ബാക്ക് ഓഫ് ചെയ്ത് വീണ്ടും ശ്രമിക്കുക.
- **`5xx`** — ഒരു സെർവർ-സൈഡ് എറർ; താൽക്കാലിക പരാജയങ്ങൾ വീണ്ടും ശ്രമിക്കുക.

ഒരു സാധാരണ എറർ എൻവലപ്പ്:

```json
{
  "success": false,
  "error": "validation_failed",
  "message": "A human-readable explanation of the problem."
}
```

## ഉൽപ്പന്നം അനുസരിച്ചുള്ള റിസോഴ്സുകൾ

മുകളിലുള്ള കൺവെൻഷനുകൾ പങ്കിടുന്നവയാണ്, പക്ഷേ ഓരോ ഉൽപ്പന്നവും അതിന്റേതായ എൻഡ്പോയിന്റുകൾ വെളിപ്പെടുത്തുന്നു. കൃത്യമായ റിസോഴ്സുകൾ, പാരാമീറ്ററുകൾ, ഫീൽഡ് നാമങ്ങൾ എന്നിവയ്ക്ക് ഉൽപ്പന്നത്തിന്റെ ഡെവലപ്പർ പേജിൽ നിന്ന് ആരംഭിക്കുക:

- **Calendar** — event types, availability **slots**, bookings (create, reschedule, cancel), calendars, webhooks, API keys, event links. Webhook ഇവന്റുകൾ `booking.created`, `booking.cancelled`, `booking.rescheduled`, `booking.no_show` എന്നിവയാണ്. [Calendar ഡെവലപ്പർമാർക്കായി](/calendar/developers) കാണുക.
- **Survey** — forms, responses, response aggregation, AI form generation, webhooks (`response.created`, `response.flagged`, `response.updated`, `form.published`, `form.closed`). [Survey ഡെവലപ്പർമാർക്കായി](/survey/developers) കാണുക.
- **Voice Portal** — agents, campaigns, contacts, കൂടാതെ tools, MCP server registration. [ഏജന്റുകൾക്കായുള്ള Tools & MCP](/voice/agents/tools-mcp) കാണുക.

## ബന്ധപ്പെട്ടവ

- [പ്ലാറ്റ്ഫോം അവലോകനം](./overview) — അക്കൗണ്ടുകൾ, ഓർഗനൈസേഷനുകൾ, പങ്കിട്ട ആശയങ്ങൾ.
- [AI ഏജന്റുകൾക്കായുള്ള MCP](./mcp) — AI അസിസ്റ്റന്റുകൾക്ക് നിങ്ങൾക്കായി ഈ റിസോഴ്സുകൾ കോൾ ചെയ്യാൻ അനുവദിക്കുക.
- [Calendar ഡെവലപ്പർമാർക്കായി](/calendar/developers) — Calendar-ന്റെ REST API, webhooks.
- [Survey ഡെവലപ്പർമാർക്കായി](/survey/developers) — Survey-യുടെ API, webhooks, MCP tools.