# REST API


# REST API

imatic પ્રોડક્ટ્સ REST APIs આપે છે જેને તમે તમારા પોતાના કોડથી ઑટોમેટ કરી શકો. આ પાનાં પરના સંમેલનો — પ્રમાણીકરણ, API keys, webhook signing, પેજિનેશન, રેટ લિમિટ્સ અને ભૂલો — દરેક પ્રોડક્ટમાં સમાન છે. જે અલગ પડે છે તે છે URL નો આકાર અને દરેક પ્રોડક્ટ જે **resources** ખુલ્લા કરે છે: Calendar versioned `/v1` પાથ વાપરે છે, જ્યારે Survey verb-શૈલીના `POST` endpoints વાપરે છે. દરેક પ્રોડક્ટનું ડેવલપર પાનું તેની ચોક્કસ સપાટી દસ્તાવેજ કરે છે.

:::note[ઉદાહરણો સ્પષ્ટતા માટે છે]

નીચેના request અને response સ્નિપેટ્સ કૉલ્સનો *આકાર* દર્શાવે છે — headers, auth, error envelopes — નહીં કે ચોક્કસ ફીલ્ડ-બાય-ફીલ્ડ schema. કોઈ પ્રોડક્ટના ચોક્કસ એન્ડપોઇન્ટ્સ, parameters અને ફીલ્ડ નામો માટે, તે પ્રોડક્ટના ડેવલપર પાનાંની લિંક્સ અનુસરો.

:::

## પ્રમાણીકરણ (Authentication)

imatic બે પ્રકારના ઓળખપત્રો વાપરે છે, બે અલગ-અલગ કૉલર્સ માટે:

- **JWT (session token)** — ઇમેલ અને પાસવર્ડ સાથે સાઇન ઇન કર્યા પછી વેબ ઍપ જે વાપરે છે. તે બ્રાઉઝરમાં *તમારું* પ્રતિનિધિત્વ કરે છે અને અલ્પજીવી હોય છે. તમે આને સીધું મેનેજ કરતા નથી; ઍપ કરે છે.
- **Scoped API key** — *તમારો કોડ* `v1` REST API ને કૉલ કરવા જે વાપરે છે. તમે તેને જાતે બનાવો છો, તે સ્પષ્ટ scopes ધરાવે છે, અને તે બ્રાઉઝર સત્ર સાથે સમાપ્ત થતી નથી.

સર્વર-થી-સર્વર કૉલ્સ માટે, હંમેશા API key વાપરો — ક્યારેય તમારો પાસવર્ડ કે કૉપિ કરેલ session token નહીં.

### API key મોકલવી

કીને `Authorization` header માં Bearer token તરીકે મોકલો:

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

## API keys કેવી રીતે કામ કરે છે

તમે દરેક પ્રોડક્ટના ડેવલપર વિસ્તારમાં API keys બનાવો અને મેનેજ કરો છો — ઉદાહરણ તરીકે Calendar નું **Developers → API keys** અને Survey નું **Developers → API keys**. એક કીના ત્રણ ગુણધર્મો સમજવા યોગ્ય છે:

- **`prefix.secret` ફોર્મેટ** — એક કીમાં એક જાહેર **prefix** અને એક ગુપ્ત ભાગ હોય છે, જે એક ટપકાથી જોડાયેલા હોય છે (ઉદાહરણ તરીકે `cal_abc123.s3cr3t_keymaterial` — Calendar keys ટૂંકો `cal_` prefix વાપરે છે). prefix imatic ને યાદીઓ અને લોગ્સમાં કીને ઓળખવા દે છે; secret એ સાબિત કરે છે કે તે તમારી છે.
- **એક જ વાર દર્શાવાય** — પૂર્ણ કી મૂલ્ય માત્ર તમે તેને બનાવો છો તે ક્ષણે જ દર્શાવાય છે. તે પછી, માત્ર prefix દેખાય છે.
- **Scopes** — દરેક કી તમે મંજૂર કરેલ ક્રિયાઓ સુધી મર્યાદિત હોય છે. Calendar ના scopes છે `slots:read`, `bookings:read`, `bookings:write`, અને `mcp` (`mcp` scope એ છે જે AI એજન્ટની કીને જોઈએ — જુઓ [AI એજન્ટ્સ માટે MCP](./mcp)). કોઈ request જે કીના scope કરતાં વધારે હોય તેને નકારી દેવામાં આવે છે.

:::danger[API keys ને પાસવર્ડની જેમ ગણો]

કીનું secret માત્ર એક જ વાર દર્શાવાય છે, બનાવતી વખતે. ત્યારે જ તેને કૉપિ કરો અને તેને secret manager કે environment variable માં સંગ્રહો — ક્યારેય source control, screenshot કે શેર કરેલ doc માં નહીં. જો કોઈ કી ખુલ્લી પડે, તો ડેવલપર વિસ્તારમાં **તેને રદ કરો** અને બદલી બનાવો. રદ કરવાનું તરત જ અમલમાં આવે છે.

:::

## Webhooks

ફેરફારો માટે પોલિંગ કરવાને બદલે, એક webhook URL રજિસ્ટર કરો અને જ્યારે કંઈક થાય ત્યારે imatic તેને એક ઘટના `POST` કરશે — ઉદાહરણ તરીકે Calendar માં બુકિંગ બને કે Survey માં જવાબ સબમિટ થાય. તમે દરેક પ્રોડક્ટના **Developers → Webhooks** વિસ્તારમાં webhook endpoints મેનેજ કરો છો, જ્યાં તમે એક ટેસ્ટ ડિલિવરી પણ મોકલી શકો છો.

એક ડિલિવરી લગભગ આના જેવી દેખાય છે:

```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" }
}
```

### signature ચકાસવી

દરેક ડિલિવરી તમારા endpoint ના signing secret નો ઉપયોગ કરીને **HMAC-SHA256** સાથે signed થાય છે, Stripe-શૈલીના `X-Imatic-Signature` header માં. header બે ફીલ્ડ ધરાવે છે: `t`, મોકલવાના સમયે unix-epoch **સેકન્ડ્સ**, અને `v1`, સ્ટ્રિંગ `${t}.${body}` નું hex HMAC (timestamp, એક literal ટપકું, પછી ચોક્કસ raw request body). ચકાસવા માટે, header ને વિભાજિત કરો, તમારા signing secret સાથે `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[દરેક પ્રોડક્ટ માટે ચોક્કસ scheme]

ઉપરનું `t=…,v1=…` scheme Calendar નું છે. તમે verifier ship કરો તે પહેલાં દરેક પ્રોડક્ટના ડેવલપર પાનાં પર header નામ, ફીલ્ડ્સ અને signed string ની પુષ્ટિ કરો.

:::

:::tip[ઝડપથી જવાબ આપો, પછી પ્રક્રિયા કરો]

પ્રાપ્તિ સ્વીકારવા માટે ઝડપથી `2xx` પાછું આપો, પછી કોઈપણ ધીમું કામ asynchronously કરો. જો તમારું endpoint ધીમું હોય કે ભૂલ આપે, તો ડિલિવરી ફરી પ્રયાસ થઈ શકે છે.

:::

## પેજિનેશન (Pagination)

List endpoints પરિણામો પાનાંમાં પાછા આપે છે જેથી એક જ કૉલને ક્યારેય બધું જ લોડ ન કરવું પડે. request પર paging parameters મોકલો અને આગલું પાનું મેળવવા response પર paging metadata વાંચો.

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

જ્યાં સુધી વધુ પરિણામો ન રહે ત્યાં સુધી આગલું પાનું માગતા રહો.

## રેટ લિમિટિંગ (Rate limiting)

પ્લેટફોર્મને નિષ્પક્ષ અને સ્થિર રાખવા માટે API keys રેટ લિમિટેડ હોય છે. જો તમે મર્યાદા ઓળંગો, તો API એ HTTP `429 Too Many Requests` સાથે જવાબ આપે છે. endpoint પર સતત ઘા કરવાને બદલે પાછા હટો અને ફરી પ્રયાસ કરો — આદર્શ રીતે exponential backoff અને jitter સાથે.

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

## ભૂલ-સંચાલન (Error handling)

ભૂલો પ્રમાણભૂત HTTP status codes અને એક JSON body વાપરે છે જે વર્ણવે છે કે શું ખોટું થયું. તમે જે codes સૌથી વારંવાર જોશો:

- **`400`** — request ખામીયુક્ત હતી કે validation નિષ્ફળ ગયું.
- **`401`** — ગુમ કે અમાન્ય API key.
- **`403`** — કી માન્ય છે પણ આ ક્રિયા માટે scope (કે org ઍક્સેસ) નથી.
- **`404`** — resource અસ્તિત્વમાં નથી કે આ કીને દેખાતું નથી.
- **`409`** — એક સંઘર્ષ, જેમ કે હમણાં જ લેવાયેલા slot ને બુક કરવાનો પ્રયાસ.
- **`429`** — રેટ લિમિટેડ; પાછા હટો અને ફરી પ્રયાસ કરો.
- **`5xx`** — એક સર્વર-સાઇડ ભૂલ; transient નિષ્ફળતાઓ ફરી પ્રયાસ કરો.

એક લાક્ષણિક error envelope:

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

## પ્રોડક્ટ પ્રમાણે resources

ઉપરના સંમેલનો વહેંચાયેલા છે, પણ દરેક પ્રોડક્ટ તેના પોતાના endpoints ખુલ્લા કરે છે. ચોક્કસ resources, parameters અને ફીલ્ડ નામો માટે પ્રોડક્ટના ડેવલપર પાનાંથી શરૂ કરો:

- **Calendar** — event types, availability **slots**, bookings (create, reschedule, cancel), calendars, webhooks, API keys, અને event links. Webhook events છે `booking.created`, `booking.cancelled`, `booking.rescheduled`, અને `booking.no_show`. જુઓ [Calendar for developers](/calendar/developers).
- **Survey** — forms, responses, response aggregation, AI ફોર્મ જનરેશન, અને webhooks (`form.published`, `response.submitted`). જુઓ [Survey for developers](/survey/developers).
- **Voice Portal** — agents, campaigns, અને contacts, ઉપરાંત tools અને MCP સર્વર રજિસ્ટ્રેશન. જુઓ [એજન્ટ્સ માટે Tools અને MCP](/voice/agents/tools-mcp).

## સંબંધિત

- [પ્લેટફોર્મ ઝાંખી](./overview) — એકાઉન્ટ્સ, સંસ્થાઓ, અને સહિયારા ખ્યાલો.
- [AI એજન્ટ્સ માટે MCP](./mcp) — AI સહાયકોને તમારા માટે આ resources કૉલ કરવા દો.
- [Calendar for developers](/calendar/developers) — Calendar નું REST API અને webhooks.
- [Survey for developers](/survey/developers) — Survey નું API, webhooks, અને MCP tools.