# REST API


# REST API

imatic ఉత్పత్తులు మీరు మీ స్వంత కోడ్ నుండి ఆటోమేట్ చేయగల REST APIలను అందిస్తాయి. ఈ పేజీలోని సంప్రదాయాలు — ప్రామాణీకరణ, API కీలు, వెబ్‌హుక్ సంతకం, పేజినేషన్, రేట్ పరిమితులు, మరియు ఎర్రర్‌లు — ఉత్పత్తుల అంతటా ఒకే విధంగా ఉంటాయి. తేడా ఉండేది 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` ఫార్మాట్** — ఒక కీకి ఒక పబ్లిక్ **ప్రిఫిక్స్** మరియు ఒక రహస్య భాగం ఉంటుంది, ఒక చుక్క ద్వారా కలపబడ్డాయి (ఉదాహరణకు `cal_abc123.s3cr3t_keymaterial` — Calendar కీలు ఒక చిన్న `cal_` ప్రిఫిక్స్‌ను ఉపయోగిస్తాయి). ప్రిఫిక్స్ జాబితాలు మరియు లాగ్‌లలో కీని గుర్తించడానికి imaticను అనుమతిస్తుంది; రహస్యం అది మీదేనని నిరూపించేది.
- **ఒకసారి చూపబడుతుంది** — మీరు దాన్ని సృష్టించిన క్షణంలో మాత్రమే పూర్తి కీ విలువ ప్రదర్శించబడుతుంది. ఆ తరువాత, ప్రిఫిక్స్ మాత్రమే కనిపిస్తుంది.
- **స్కోప్‌లు** — ప్రతి కీ మీరు మంజూరు చేసిన చర్యలకు పరిమితం. Calendar యొక్క స్కోప్‌లు `slots:read`, `bookings:read`, `bookings:write`, మరియు `mcp` (`mcp` స్కోప్ ఒక AI ఏజెంట్ కీకి అవసరమైనది — [AI ఏజెంట్‌ల కోసం MCP](./mcp) చూడండి). ఒక కీ స్కోప్‌ను మించిన అభ్యర్థన తిరస్కరించబడుతుంది.

:::danger[API కీలను పాస్‌వర్డ్‌ల వలె భావించండి]

ఒక కీ యొక్క రహస్యం ఒకసారి మాత్రమే, సృష్టి సమయంలో చూపబడుతుంది. అప్పుడు దాన్ని కాపీ చేసి ఒక సీక్రెట్ మేనేజర్ లేదా ఎన్విరాన్‌మెంట్ వేరియబుల్‌లో నిల్వ చేయండి — ఎప్పుడూ సోర్స్ కంట్రోల్, ఒక స్క్రీన్‌షాట్, లేదా ఒక షేర్డ్ డాక్‌లో కాదు. ఒక కీ బయటపడితే, దాన్ని డెవలపర్ ప్రాంతంలో **రద్దు చేయండి** మరియు ఒక ప్రత్యామ్నాయాన్ని సృష్టించండి. రద్దు తక్షణమే అమలులోకి వస్తుంది.

:::

## వెబ్‌హుక్‌లు

మార్పుల కోసం పోల్ చేయడం కంటే, ఒక వెబ్‌హుక్ URLను నమోదు చేయండి, మరియు ఏదైనా జరిగినప్పుడు imatic దానికి ఒక ఈవెంట్‌ను `POST` చేస్తుంది — ఉదాహరణకు Calendarలో ఒక బుకింగ్ సృష్టించబడింది లేదా Surveyలో ఒక ప్రతిస్పందన సమర్పించబడింది. మీరు ప్రతి ఉత్పత్తి యొక్క **Developers → Webhooks** ప్రాంతంలో వెబ్‌హుక్ ఎండ్‌పాయింట్‌లను నిర్వహిస్తారు, అక్కడ మీరు ఒక పరీక్ష డెలివరీని కూడా పంపవచ్చు.

ఒక డెలివరీ స్థూలంగా ఇలా కనిపిస్తుంది:

```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`ను తిరిగి లెక్కించండి, మరియు స్థిర సమయంలో పోల్చండి. అవి సరిపోలకపోతే తిరస్కరించండి — మరియు రీప్లేకి వ్యతిరేకంగా రక్షించడానికి `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 యొక్క. మీరు ఒక వెరిఫయర్‌ను షిప్ చేసే ముందు ప్రతి ఉత్పత్తి యొక్క డెవలపర్ పేజీలో హెడర్ పేరు, ఫీల్డ్‌లు, మరియు సంతకం చేయబడిన స్ట్రింగ్‌ను నిర్ధారించండి.

:::

:::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** — ఈవెంట్ రకాలు, అందుబాటు **slots**, బుకింగ్‌లు (సృష్టించడం, రీషెడ్యూల్, రద్దు), క్యాలెండర్‌లు, వెబ్‌హుక్‌లు, API కీలు, మరియు ఈవెంట్ లింక్‌లు. వెబ్‌హుక్ ఈవెంట్‌లు `booking.created`, `booking.cancelled`, `booking.rescheduled`, మరియు `booking.no_show`. [డెవలపర్‌ల కోసం Calendar](/calendar/developers) చూడండి.
- **Survey** — ఫారమ్‌లు, ప్రతిస్పందనలు, ప్రతిస్పందన సముదాయీకరణ, AI ఫారమ్ ఉత్పత్తి, మరియు వెబ్‌హుక్‌లు (`form.published`, `response.submitted`). [డెవలపర్‌ల కోసం Survey](/survey/developers) చూడండి.
- **Voice Portal** — ఏజెంట్‌లు, ప్రచారాలు, మరియు సంప్రదింపులు, ప్లస్ సాధనాలు మరియు MCP సర్వర్ నమోదు. [ఏజెంట్‌ల కోసం సాధనాలు & MCP](/voice/agents/tools-mcp) చూడండి.

## సంబంధితం

- [ప్లాట్‌ఫారమ్ అవలోకనం](./overview) — ఖాతాలు, సంస్థలు, మరియు షేర్డ్ భావనలు.
- [AI ఏజెంట్‌ల కోసం MCP](./mcp) — AI అసిస్టెంట్‌లు మీ కోసం ఈ వనరులను కాల్ చేయనివ్వండి.
- [డెవలపర్‌ల కోసం Calendar](/calendar/developers) — Calendar యొక్క REST API మరియు వెబ్‌హుక్‌లు.
- [డెవలపర్‌ల కోసం Survey](/survey/developers) — Survey యొక్క API, వెబ్‌హుక్‌లు, మరియు MCP సాధనాలు.