# API संदर्भ

## परिचय

यह पेज Nibomo के लिए बाहरी AI एजेंटों के मौजूदा अनुबंध का विवरण देता है।

अगर आपका क्लाइंट MCP बोलता है, तो [MCP कनेक्टर](/hi/docs/mcp-connector/) कनेक्ट करने का
सबसे सरल तरीका है और यह इसी डेटा इंटरफ़ेस को अपने भीतर समेटता है। यह पेज CLI एजेंटों
द्वारा उपयोग किए जाने वाले HTTP खोज, SQL, गाइड और समीक्षा अनुबंध का विवरण देता है।

शुरुआत मानक खोज प्रवेश बिंदु से करें:

```text
GET https://api.flashcards-open-source-app.com/v1/
```

यही जानकारी `GET /v1/agent` पर भी उपलब्ध है, लेकिन `/v1/` ही मुख्य सार्वजनिक प्रवेश बिंदु है।

यह जानकारी किसी एजेंट को बताती है कि वह कैसे:

- email OTP login शुरू करे
- OTP को लंबे समय तक मान्य रहने वाली API key में बदल दे
- account context प्राप्त करे
- workspace बनाए या चुने
- प्रकाशित SQL इंटरफ़ेस के जरिए आगे बढ़े
- संदर्भ गाइड प्राप्त करे और एक-एक करके कार्डों की समीक्षा करे

## रनटाइम डिस्कवरी और स्रोत

OpenAPI उपलब्ध नहीं है। नीचे दिए गए चार पुराने specification URLs अब schema के बजाय `"openapiAvailable": false` वाला एक ही JSON discovery notice लौटाते हैं:

- `https://api.flashcards-open-source-app.com/v1/agent/openapi.json`
- `https://api.flashcards-open-source-app.com/v1/agent/swagger.json`
- `https://api.flashcards-open-source-app.com/v1/openapi.json`
- `https://api.flashcards-open-source-app.com/v1/swagger.json`

वर्तमान runtime discovery के लिए `GET https://api.flashcards-open-source-app.com/v1/` का उपयोग करें। runtime routes के लिए लौटाए गए `docs.discoveryUrl` और implementation details के लिए `docs.source.agentRoutesUrl` का पालन करें।

## प्रमाणीकरण की शुरुआती प्रक्रिया

OTP की शुरुआती प्रक्रिया auth सेवा पर चलती है:

- `POST https://auth.flashcards-open-source-app.com/api/agent/send-code`
- `POST https://auth.flashcards-open-source-app.com/api/agent/verify-code`

यह क्रम इस प्रकार है:

1. `GET /v1/` पर अनुरोध भेजें।
2. उपयोगकर्ता का ईमेल `send-code` पर भेजें।
3. उत्तर से `otpSessionToken` पढ़ें।
4. उपयोगकर्ता से सबसे हाल का 8-digit email code पूछें।
5. `verify-code` को `code`, `otpSessionToken`, और `label` के साथ भेजें।
6. वापस मिली API key को chat memory के बाहर सुरक्षित रखें।

अनुशंसित परिवेश चर:

```bash
export FLASHCARDS_OPEN_SOURCE_API_KEY="fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS"
```

प्रमाणित अनुरोधों में यह header उपयोग होता है:

```text
Authorization: ApiKey <key>
```

उदाहरण क्रम:

```bash
curl https://api.flashcards-open-source-app.com/v1/
```

```bash
curl -X POST https://auth.flashcards-open-source-app.com/api/agent/send-code \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
```

```bash
curl -X POST https://auth.flashcards-open-source-app.com/api/agent/verify-code \
  -H "Content-Type: application/json" \
  -d '{
    "code":"12345678",
    "otpSessionToken":"...",
    "label":"Codex on MacBook"
  }'
```

## लॉग इन के बाद उपलब्ध एजेंट इंटरफ़ेस

सत्यापन के बाद उपलब्ध एजेंट इंटरफ़ेस यह है:

- `GET /v1/agent/me`
- `GET /v1/agent/workspaces`
- `POST /v1/agent/workspaces`
- `POST /v1/agent/workspaces/{workspaceId}/select`
- `POST /v1/agent/sql/query` (केवल पढ़ने के लिए)
- `POST /v1/agent/sql/execute` (लिखने के लिए)
- `GET /v1/agent/guide/{topic}` (केवल पढ़ने के लिए)
- `POST /v1/agent/reviews/next` (केवल पढ़ने के लिए)
- `POST /v1/agent/reviews/reveal` (केवल पढ़ने के लिए)
- `POST /v1/agent/reviews/submit` (लिखने के लिए)

सामान्य शुरुआती क्रम इस तरह होता है:

1. `GET /v1/agent/me`
2. `GET /v1/agent/workspaces?limit=100`
3. जरूरत हो तो `POST /v1/agent/workspaces` with `{"name":"Personal"}`
4. जरूरत हो तो `POST /v1/agent/workspaces/{workspaceId}/select`
5. पढ़ने के लिए `POST /v1/agent/sql/query` और लिखने के लिए `POST /v1/agent/sql/execute` का उपयोग करें

हर API key connection के लिए workspace selection अलग से स्पष्ट रूप से किया जाता है। अगला कदम अनुमान से तय करने के बजाय एजेंटों को लौटाए गए `instructions` text और runtime routes के लिए `docs.discoveryUrl`, साथ ही implementation details के लिए `docs.source.agentRoutesUrl` का पालन करना चाहिए।

SQL और समीक्षा routes JSON body में एक वैकल्पिक `workspaceId` भी स्वीकार करते हैं। यह workspace selection बदले बिना केवल एक कॉल के लिए उस workspace को लक्षित करता है; चुने हुए workspace का उपयोग करने के लिए इसे छोड़ दें। जब न कोई selection हो और न कोई `workspaceId`, तो वे `409 WORKSPACE_SELECTION_REQUIRED` लौटाते हैं।

## SQL इंटरफ़ेस

`POST /v1/agent/sql/query` सख्ती से केवल पढ़ने का इंटरफ़ेस है (`SHOW TABLES`, `DESCRIBE`, `SHOW COLUMNS`, `SELECT`) और `POST /v1/agent/sql/execute` लिखने का इंटरफ़ेस है (`INSERT`, `UPDATE`, `DELETE`); एक ही कॉल या तो पूरी तरह पढ़ने की होनी चाहिए या पूरी तरह लिखने की।

इसे जानबूझकर सीमित रखा गया है; यह पूरा PostgreSQL नहीं है। ये दस्तावेज़ केवल
समर्थित बोली को कवर करते हैं, PostgreSQL compatibility reference नहीं हैं।

कोई भी read path डेटा की मरम्मत, scheduling की पुनर्गणना, या कार्ड state में
बदलाव नहीं करता। कार्ड और डेक के हर write के लिए `POST /v1/agent/sql/execute` का
उपयोग करें। SQL `review_events` या FSRS scheduling state नहीं लिख सकता; समीक्षाएँ
`POST /v1/agent/reviews/submit` के जरिए दर्ज करें।

फ़िलहाल समर्थित स्टेटमेंट प्रकार:

- `SHOW TABLES`
- `DESCRIBE <resource>`
- `SHOW COLUMNS FROM <resource>`
- `SELECT`
- `INSERT`
- `UPDATE`
- `DELETE`

फ़िलहाल प्रकाशित तार्किक संसाधनों में ये शामिल हैं:

- `workspace`
- `cards`
- `decks`
- `review_events`

ध्यान देने योग्य बातें:

- `LIMIT` का default `100` है और इसकी अधिकतम सीमा भी `100` ही है
- स्थिर pagination चाहिए तो `ORDER BY` का उपयोग करें
- schema जानने के लिए `SHOW TABLES` या `DESCRIBE cards` का उपयोग करें
- हर SQL कॉल एक workspace तक सीमित है: body में दिया गया `workspaceId`, या चुना हुआ workspace

उदाहरण अनुरोध:

```bash
curl -X POST https://api.flashcards-open-source-app.com/v1/agent/sql/query \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY" \
  -d '{"sql":"SHOW TABLES"}'
```

उदाहरण कार्ड क्वेरी:

```bash
curl -X POST https://api.flashcards-open-source-app.com/v1/agent/sql/query \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY" \
  -d '{
    "sql":"SELECT card_id, front_text, back_text, tags FROM cards ORDER BY updated_at DESC LIMIT 20 OFFSET 0"
  }'
```

उदाहरण बदलाव अनुरोध:

```bash
curl -X POST https://api.flashcards-open-source-app.com/v1/agent/sql/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY" \
  -d '{
    "sql":"UPDATE cards SET back_text = '\''Updated answer'\'' WHERE card_id = '\''50b5b928-7f04-4cc8-878d-6cd0e8b98474'\''"
  }'
```

`https://mcp.nibomo.com/mcp` पर एक रिमोट MCP सर्वर भी उपलब्ध है, जो OAuth 2.1 (Dynamic Client Registration + PKCE) का उपयोग करता है। यह वही SQL विभाजन `sql_query` (सख्ती से केवल पढ़ने के लिए) और `sql_execute` (लिखने के लिए) के रूप में देता है, साथ ही `list_workspaces`, `get_guide`, और समीक्षा टूल `next_review_card`, `reveal_answer` और `submit_review`; देखें [MCP कनेक्टर](/hi/docs/mcp-connector/)।

### सुरक्षा और दायरा

SQL सतह कच्चे PostgreSQL के बजाय एक सीमित, पार्सर-लागू बोली है। सुरक्षा उपाय इस प्रकार हैं:

- **बंद स्टेटमेंट अनुमति-सूची**: पढ़ने के लिए केवल `SHOW TABLES`, `DESCRIBE`, `SHOW COLUMNS` और `SELECT`, तथा लिखने के लिए `INSERT`, `UPDATE` और `DELETE`। बाकी सब कुछ पार्स के समय अस्वीकार कर दिया जाता है।
- **सीमित संसाधन**: स्टेटमेंट केवल `workspace`, `cards`, `decks` और `review_events` संसाधनों को ही छू सकते हैं।
- **प्रति-वर्कस्पेस दायरा**: हर स्टेटमेंट आपकी पहुँच वाले एक वर्कस्पेस तक सीमित है, या तो request body में दिया गया `workspaceId` या आपका चुना हुआ वर्कस्पेस, किसी अन्य टेनेंट तक पहुँच नहीं।
- **सख्त request body**: SQL और समीक्षा routes किसी अज्ञात body field को अस्वीकार करते हैं, इसलिए गलत वर्तनी वाला `workspaceId` चुने हुए वर्कस्पेस पर चलने के बजाय विफल हो जाता है।
- **सीमाएँ**: प्रति स्टेटमेंट अधिकतम `100` पंक्तियाँ, प्रति बैच अधिकतम `50` स्टेटमेंट, और परिणाम की सीमा लगभग `12k` टोकन। म्यूटेशन बैच परमाणु रूप से लागू होते हैं।
- **पढ़ने/लिखने का विभाजन**: `sql_query` और `list_workspaces` सख्ती से केवल पढ़ने के लिए हैं (`readOnlyHint`) और डेटा की मरम्मत, scheduling की पुनर्गणना, या कार्ड state में बदलाव कभी नहीं करते। `sql_execute` एकमात्र SQL write tool है और लिखने का कार्य करता है (`destructiveHint`); एक ही कॉल या तो पूरी तरह पढ़ने की होनी चाहिए या पूरी तरह लिखने की। SQL `review_events` या FSRS scheduling state नहीं लिख सकता; केवल `POST /v1/agent/reviews/submit` (MCP `submit_review`) ही समीक्षा दर्ज करता है।

## गाइड

`GET /v1/agent/guide/{topic}` `data.guide` में एक संदर्भ गाइड लौटाता है, यह वही सामग्री है जो MCP `get_guide` टूल देता है। विषय:

- `sql_dialect`: पूरा SQL व्याकरण, सीमाएँ और उदाहरण
- `card_authoring`: कार्ड अनुबंध, tags, डुप्लिकेट जाँच और फ़ॉर्मैटिंग
- `bulk_authoring`: किसी बड़े write job को बाँटना और सत्यापित करना
- `review_flow`: समीक्षा और रेटिंग का चक्र

अज्ञात विषय पर समर्थित विषयों की सूची के साथ `400` उत्तर मिलता है। कार्ड लिखने, बड़ी मात्रा में लिखने, या समीक्षा चलाने से पहले संबंधित गाइड प्राप्त करें, और किसी स्टेटमेंट के अस्वीकार होने के बाद `sql_dialect` फिर से पढ़ें।

```bash
curl https://api.flashcards-open-source-app.com/v1/agent/guide/sql_dialect \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY"
```

## समीक्षाएँ

समीक्षा routes किसी एजेंट को एक समय में एक कार्ड पर शिक्षार्थी से प्रश्न पूछने और हर रेटिंग को कार्ड के FSRS schedule में सहेजने देते हैं। ये वही JSON arguments लेते हैं जो MCP समीक्षा टूल लेते हैं:

- `POST /v1/agent/reviews/next` `cardId` और `frontText` के साथ `card` लौटाता है, या कुछ भी बकाया न होने पर `card: null`। वैकल्पिक `tags` (इनमें से कोई भी) या `deckId` कतार को सीमित करता है, दोनों एक साथ कभी नहीं; बिना body वाला अनुरोध भी मान्य है।
- `POST /v1/agent/reviews/reveal` के लिए `cardId` आवश्यक है और यह उस कार्ड का `backText` लौटाता है।
- `POST /v1/agent/reviews/submit` के लिए `cardId`, क्लाइंट द्वारा बनाया गया एक `reviewId` UUID, `Again`, `Hard`, `Good` या `Easy` में से एक `rating`, और शिक्षार्थी का IANA `reviewedTimeZone` आवश्यक है। सर्वर समीक्षा का समय दर्ज करता है और कार्ड का नया schedule लौटाता है, जिसमें `dueAt`, `state`, `reps` और `lapses` शामिल हैं।

तीनों routes वैकल्पिक `workspaceId` स्वीकार करते हैं। सबमिट करने से पहले `reviewId` को सुरक्षित रखें, और किसी अनिश्चित सबमिशन को बिल्कुल उसी अनुरोध के साथ दोबारा आज़माएँ; यह कभी दूसरी समीक्षा दर्ज नहीं करता। समीक्षा routes ये उत्तर भी दे सकते हैं:

- `409 REVIEW_EVENT_CONFLICT`: समीक्षा पहले ही दर्ज हो चुकी है, और `error.details.reviewSchedule` में कार्ड का वर्तमान schedule होता है।
- `409 REVIEW_ID_CARD_MISMATCH`: `reviewId` पहले से किसी दूसरे कार्ड की समीक्षा की पहचान करता है, इसलिए कुछ भी संग्रहीत नहीं हुआ; नए `reviewId` के साथ फिर से सबमिट करें।
- `409 REVIEW_STALE`: कार्ड का संग्रहीत समीक्षा समय वर्तमान सर्वर समय के बराबर या उसके बाद का है; किसी दूसरे कार्ड की समीक्षा करें।
- `400 REVIEW_INPUT_INVALID`: कोई argument गायब, अमान्य या असमर्थित है, जिसमें `deckId` के साथ मिलाए गए `tags` या ऐसा tag शामिल है जिसका workspace उपयोग नहीं करता।

उदाहरण सबमिशन:

```bash
curl -X POST https://api.flashcards-open-source-app.com/v1/agent/reviews/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY" \
  -d '{
    "cardId":"693c4863-28a2-45e8-8f55-9fa31fc95ff2",
    "reviewId":"429bb7cc-40fb-49f3-bb50-48a5db2826d1",
    "rating":"Good",
    "reviewedTimeZone":"Europe/Sofia"
  }'
```

## उपयोगकर्ता और समन्वयन API

Nibomo में उपयोगकर्ता क्लाइंट और offline-first sync के लिए अलग APIs भी हैं, लेकिन बाहरी एजेंटों के लिए वे मुख्य अनुबंध नहीं हैं:

- browser आधारित flows shared-domain cookies और CSRF protection का उपयोग करते हैं
- offline-first क्लाइंट `/v1/workspaces/{workspaceId}/sync/push` और `/v1/workspaces/{workspaceId}/sync/pull` के तहत लागू किए गए sync routes का उपयोग करते हैं
- sync routes बाहरी एजेंट इंटरफ़ेस से अलग हैं

---
*[इस पेज का styled HTML संस्करण देखें](<https://nibomo.com/hi/docs/api/>)*

*AI agent इस सेवा में उपयोगकर्ता का अकाउंट `GET https://api.flashcards-open-source-app.com/v1/` से शुरू करके बना सकते हैं। सेटअप के बाद, वे MCP के जरिए `https://mcp.nibomo.com/mcp` पर भी कनेक्ट कर सकते हैं।*

*टिप: https://nibomo.com पर किसी भी URL के अंत में `.md` जोड़ें ताकि उसका साफ़ Markdown संस्करण मिले।*