# API குறிப்பு

## கண்ணோட்டம்

Nibomo க்கான தற்போதைய வெளிப்புற AI முகவர் ஒப்பந்தத்தை இந்தப் பக்கம் விவரிக்கிறது.

உங்கள் கிளையண்ட் MCP ஐ ஆதரித்தால், இணைவதற்கான மிக எளிய வழி [MCP இணைப்பான்](/ta/docs/mcp-connector/);
அது இதே தரவு இடைமுகத்தை உள்ளடக்கியுள்ளது. CLI முகவர்கள் பயன்படுத்தும் HTTP கண்டறிதல், SQL,
வழிகாட்டி, மீள்பயிற்சி ஒப்பந்தத்தை இந்தப் பக்கம் விவரிக்கிறது.

அதிகாரப்பூர்வ கண்டறிதல் நுழைவுப் புள்ளியிலிருந்து தொடங்குங்கள்:

```text
GET https://api.nibomo.com/v1/
```

இதே கண்டறிதல் உள்ளடக்கம் `GET /v1/agent` இலும் கிடைக்கிறது, ஆனால் முதன்மைப் பொது நுழைவுப் புள்ளி `/v1/` தான்.

கண்டறிதல் பதில் ஒரு முகவருக்குப் பின்வருவனவற்றை எப்படிச் செய்வது என்று சொல்கிறது:

- மின்னஞ்சல் OTP உள்நுழைவைத் தொடங்குதல்
- OTP ஐக் கொடுத்து நீண்ட காலம் செல்லுபடியாகும் API விசையைப் பெறுதல்
- கணக்குச் சூழலை ஏற்றுதல்
- ஒரு பணியிடத்தை உருவாக்குதல் அல்லது தேர்ந்தெடுத்தல்
- வெளியிடப்பட்ட SQL இடைமுகம் வழியாகத் தொடர்தல்
- குறிப்பு வழிகாட்டிகளைப் பெறுதல், அட்டைகளை ஒவ்வொன்றாக மீள்பயிற்சி செய்தல்

## இயக்க நேரக் கண்டறிதலும் மூலக் குறியீடும்

OpenAPI கிடைக்காது. கீழே உள்ள நான்கு முன்னாள் விவரக்குறிப்பு URL களும் இப்போது ஒரு திட்டவரைவுக்குப் பதிலாக `"openapiAvailable": false` கொண்ட அதே JSON கண்டறிதல் அறிவிப்பைத் தருகின்றன:

- `https://api.nibomo.com/v1/agent/openapi.json`
- `https://api.nibomo.com/v1/agent/swagger.json`
- `https://api.nibomo.com/v1/openapi.json`
- `https://api.nibomo.com/v1/swagger.json`

தற்போதைய இயக்க நேரக் கண்டறிதலுக்கு `GET https://api.nibomo.com/v1/` ஐப் பயன்படுத்துங்கள். இயக்க நேர வழிகளுக்குப் பதிலில் வரும் `docs.discoveryUrl` ஐயும், செயலாக்க விவரங்களுக்கு `docs.source.agentRoutesUrl` ஐயும் பின்பற்றுங்கள்.

## அங்கீகாரத் தொடக்க அமைப்பு

OTP தொடக்க அமைப்பு அங்கீகாரச் சேவையில் இயங்குகிறது:

- `POST https://auth.nibomo.com/api/agent/send-code`
- `POST https://auth.nibomo.com/api/agent/verify-code`

ஓட்டம் இதுதான்:

1. `GET /v1/` ஐ அழையுங்கள்.
2. பயனரின் மின்னஞ்சலை `send-code` க்கு அனுப்புங்கள்.
3. பதிலிலிருந்து `otpSessionToken` ஐப் படியுங்கள்.
4. மின்னஞ்சலில் வந்த சமீபத்திய 8 இலக்கக் குறியீட்டைப் பயனரிடம் கேளுங்கள்.
5. `code`, `otpSessionToken`, `label` ஆகியவற்றுடன் `verify-code` ஐ அழையுங்கள்.
6. திருப்பி அனுப்பப்பட்ட API விசையை அரட்டை நினைவகத்துக்கு வெளியே சேமித்து வையுங்கள்.

பரிந்துரைக்கப்படும் சூழல் மாறி:

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

அங்கீகரிக்கப்பட்ட கோரிக்கைகள் இதைப் பயன்படுத்துகின்றன:

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

தொடக்க அமைப்பு வரிசைக்கு ஓர் எடுத்துக்காட்டு:

```bash
curl https://api.nibomo.com/v1/
```

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

```bash
curl -X POST https://auth.nibomo.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. தேவைப்பட்டால், `{"name":"Personal"}` உடன் `POST /v1/agent/workspaces`
4. தேவைப்பட்டால், `POST /v1/agent/workspaces/{workspaceId}/select`
5. படிப்பதற்கு `POST /v1/agent/sql/query` ஐயும், எழுதுவதற்கு `POST /v1/agent/sql/execute` ஐயும் பயன்படுத்துங்கள்

பணியிடத் தேர்வு ஒவ்வொரு API விசை இணைப்புக்கும் வெளிப்படையாகச் செய்யப்படுகிறது. அடுத்த படியை ஊகிப்பதற்குப் பதிலாக, முகவர்கள் திருப்பி அனுப்பப்படும் `instructions` உரையையும், இயக்க நேர வழிகளுக்கு `docs.discoveryUrl` ஐயும், செயலாக்க விவரங்களுக்கு `docs.source.agentRoutesUrl` ஐயும் பின்பற்ற வேண்டும்.

SQL, மீள்பயிற்சி வழிகள் JSON உள்ளடக்கத்தில் விருப்பத்தேர்வான `workspaceId` ஐயும் ஏற்கின்றன. தேர்வை மாற்றாமல் ஓர் அழைப்புக்கு மட்டும் அது அந்தப் பணியிடத்தைக் குறிவைக்கிறது; தேர்ந்தெடுக்கப்பட்ட பணியிடத்தைப் பயன்படுத்த அதை விட்டுவிடுங்கள். தேர்வும் இல்லாமல் `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 இணக்கத்தன்மைக்கான குறிப்பு அல்ல.

எந்தப் படிக்கும் வழியும் தரவைச் சரிசெய்வதில்லை, திட்டமிடலை மீண்டும் கணக்கிடுவதில்லை, அட்டையின் நிலையை மாற்றுவதில்லை. அட்டைகளிலும்
அட்டைத் தொகுப்புகளிலும் செய்யும் ஒவ்வொரு எழுதுதலுக்கும் `POST /v1/agent/sql/execute` ஐப் பயன்படுத்துங்கள். SQL ஆல் `review_events` ஐயோ
FSRS திட்டமிடல் நிலையையோ எழுத முடியாது; மீள்பயிற்சிகளை
`POST /v1/agent/reviews/submit` மூலம் பதிவு செய்யுங்கள்.

தற்போதைய கூற்று வகைகள்:

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

தற்போது வெளியிடப்பட்டுள்ள தர்க்க வளங்கள்:

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

குறிப்புகள்:

- `LIMIT` இயல்பாக `100`, அதிகபட்சமும் `100`
- நிலையான பக்கமாக்கல் தேவைப்படும்போது `ORDER BY` ஐப் பயன்படுத்துங்கள்
- திட்டவரைவைக் கண்டறிய `SHOW TABLES` அல்லது `DESCRIBE cards` ஐப் பயன்படுத்துங்கள்
- ஒவ்வொரு SQL அழைப்பும் ஒரே பணியிடத்துக்குள் அடங்கும்: கோரிக்கை உள்ளடக்கத்தில் உள்ள `workspaceId`, அல்லது தேர்ந்தெடுக்கப்பட்ட பணியிடம்

கோரிக்கைக்கு ஓர் எடுத்துக்காட்டு:

```bash
curl -X POST https://api.nibomo.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.nibomo.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.nibomo.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'\''"
  }'
```

OAuth 2.1 (Dynamic Client Registration + PKCE) பயன்படுத்தும் தொலைநிலை MCP சேவையகமும் `https://mcp.nibomo.com/mcp` இல் கிடைக்கிறது. அது இதே SQL பிரிவை `sql_query` (கண்டிப்பாகப் படிக்க மட்டும்), `sql_execute` (எழுதுதல்) என வழங்குகிறது; அவற்றுடன் `list_workspaces`, `get_guide`, மீள்பயிற்சிக் கருவிகளான `next_review_card`, `reveal_answer`, `submit_review` ஆகியவற்றையும் வழங்குகிறது; [MCP இணைப்பான்](/ta/docs/mcp-connector/) ஐப் பாருங்கள்.

### பாதுகாப்பும் வரம்பும்

SQL இடைமுகம் நேரடி PostgreSQL அல்ல; அது பாகுபடுத்தியால் கட்டுப்படுத்தப்படும், வரம்புக்குட்பட்ட ஒரு மொழிவழக்கு. பாதுகாப்பு வரம்புகள்:

- **மூடிய கூற்று அனுமதிப் பட்டியல்**: படிப்பதற்கு `SHOW TABLES`, `DESCRIBE`, `SHOW COLUMNS`, `SELECT` மட்டும், எழுதுவதற்கு `INSERT`, `UPDATE`, `DELETE` மட்டும். வேறு எதுவும் பாகுபடுத்தும் நேரத்திலேயே நிராகரிக்கப்படும்.
- **வரம்புக்குட்பட்ட வளங்கள்**: கூற்றுகள் `workspace`, `cards`, `decks`, `review_events` வளங்களை மட்டுமே தொட முடியும்.
- **பணியிட வாரியான வரம்பு**: ஒவ்வொரு கூற்றும் நீங்கள் அணுகக்கூடிய ஒரே பணியிடத்துக்குள் அடங்கும்; அது கோரிக்கை உள்ளடக்கத்தில் உள்ள `workspaceId` அல்லது நீங்கள் தேர்ந்தெடுத்த பணியிடம். மற்ற பணியிடங்களின் தரவை அணுக முடியாது.
- **கண்டிப்பான கோரிக்கை உள்ளடக்கங்கள்**: SQL, மீள்பயிற்சி வழிகள் அறியப்படாத உள்ளடக்கப் புலத்தை நிராகரிக்கின்றன, எனவே எழுத்துப்பிழையுடன் உள்ள `workspaceId` தேர்ந்தெடுக்கப்பட்ட பணியிடத்தில் இயங்குவதற்குப் பதிலாகத் தோல்வியடையும்.
- **உச்ச வரம்புகள்**: ஒரு கூற்றுக்கு அதிகபட்சம் `100` வரிசைகள், ஒரு தொகுதிக்கு அதிகபட்சம் `50` கூற்றுகள், முடிவுக்குத் தோராயமாக `12k` டோக்கன்கள் வரம்பு. மாற்றத் தொகுதிகள் அனைத்தும் ஒன்றாக அல்லது எதுவுமே இல்லாமல் (atomic) பயன்படுத்தப்படுகின்றன.
- **படித்தல்/எழுதுதல் பிரிவு**: `sql_query`, `list_workspaces` கண்டிப்பாகப் படிக்க மட்டுமானவை (`readOnlyHint`); அவை ஒருபோதும் தரவைச் சரிசெய்வதில்லை, திட்டமிடலை மீண்டும் கணக்கிடுவதில்லை, அட்டையின் நிலையை மாற்றுவதில்லை. `sql_execute` மட்டுமே SQL எழுதும் கருவி, அது எழுதும் செயல்பாடுகளைச் செய்கிறது (`destructiveHint`); ஓர் அழைப்பில் உள்ளவை அனைத்தும் படிக்கும் செயல்பாடுகளாகவோ அனைத்தும் எழுதும் செயல்பாடுகளாகவோ இருக்க வேண்டும். SQL ஆல் `review_events` ஐயோ FSRS திட்டமிடல் நிலையையோ எழுத முடியாது; `POST /v1/agent/reviews/submit` (MCP `submit_review`) மட்டுமே ஒரு மீள்பயிற்சியைப் பதிவு செய்கிறது.

## வழிகாட்டிகள்

`GET /v1/agent/guide/{topic}` ஒரு குறிப்பு வழிகாட்டியை `data.guide` இல் தருகிறது; MCP `get_guide` கருவி வழங்கும் அதே உள்ளடக்கம் இது. தலைப்புகள்:

- `sql_dialect`: முழு SQL இலக்கணம், வரம்புகள், எடுத்துக்காட்டுகள்
- `card_authoring`: அட்டை ஒப்பந்தம், குறிச்சொற்கள், நகல் சரிபார்ப்புகள், வடிவமைப்பு
- `bulk_authoring`: பெரிய எழுதும் பணியைப் பிரித்தலும் சரிபார்த்தலும்
- `review_flow`: மீள்பயிற்சி, மதிப்பீட்டுச் சுழற்சி

அறியப்படாத தலைப்புக்கு ஆதரிக்கப்படும் தலைப்புகளின் பட்டியலுடன் `400` பதில் வரும். அட்டைகளை உருவாக்குவதற்கு முன், பெருமளவில் எழுதுவதற்கு முன், அல்லது மீள்பயிற்சியை நடத்துவதற்கு முன் பொருத்தமான வழிகாட்டியைப் பெறுங்கள்; ஒரு கூற்று நிராகரிக்கப்பட்ட பிறகு `sql_dialect` ஐ மீண்டும் படியுங்கள்.

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

## மீள்பயிற்சிகள்

மீள்பயிற்சி வழிகள் மூலம் ஒரு முகவர் கற்பவரிடம் ஒவ்வொன்றாக அட்டைகளைக் கேட்டு, ஒவ்வொரு மதிப்பீட்டையும் அட்டையின் FSRS அட்டவணையில் சேமிக்க முடியும். அவை MCP மீள்பயிற்சிக் கருவிகள் ஏற்கும் அதே JSON அளவுருக்களை ஏற்கின்றன:

- `POST /v1/agent/reviews/next` `cardId`, `frontText` உடன் `card` ஐத் தருகிறது, அல்லது மீள்பயிற்சிக்கு உரியது எதுவும் இல்லையென்றால் `card: null` ஐத் தருகிறது. விருப்பத்தேர்வான `tags` (ஏதேனும் ஒன்று பொருந்தினால் போதும்) அல்லது `deckId` வரிசையைச் சுருக்குகிறது, ஆனால் இரண்டையும் சேர்த்துப் பயன்படுத்த முடியாது; உள்ளடக்கம் இல்லாத கோரிக்கையும் செல்லுபடியானது.
- `POST /v1/agent/reviews/reveal` க்கு `cardId` தேவை; அது அந்த அட்டையின் `backText` ஐத் தருகிறது.
- `POST /v1/agent/reviews/submit` க்கு `cardId`, கிளையண்ட் உருவாக்கிய `reviewId` UUID, `Again`, `Hard`, `Good` அல்லது `Easy` என்ற `rating`, கற்பவரின் IANA `reviewedTimeZone` ஆகியவை தேவை. சேவையகம் மீள்பயிற்சி நேரத்தைப் பதிந்து, `dueAt`, `state`, `reps`, `lapses` உட்பட அட்டையின் புதிய அட்டவணையைத் தருகிறது.

மூன்று வழிகளும் விருப்பத்தேர்வான `workspaceId` ஐ ஏற்கின்றன. சமர்ப்பிப்பதற்கு முன் `reviewId` ஐச் சேமித்து வையுங்கள்; முடிவு உறுதியாகத் தெரியாத சமர்ப்பிப்பை முற்றிலும் அதே கோரிக்கையுடன் மீண்டும் அனுப்புங்கள்; அது ஒருபோதும் இரண்டாவது மீள்பயிற்சியைப் பதிவு செய்யாது. மீள்பயிற்சி வழிகள் பின்வரும் பதில்களையும் தரலாம்:

- `409 REVIEW_EVENT_CONFLICT`: மீள்பயிற்சி ஏற்கனவே பதிவு செய்யப்பட்டுவிட்டது; `error.details.reviewSchedule` அட்டையின் தற்போதைய அட்டவணையைக் கொண்டுள்ளது.
- `409 REVIEW_ID_CARD_MISMATCH`: அந்த `reviewId` ஏற்கனவே வேறொரு அட்டையின் மீள்பயிற்சியைக் குறிக்கிறது, எனவே எதுவும் சேமிக்கப்படவில்லை; புதிய `reviewId` உடன் மீண்டும் சமர்ப்பியுங்கள்.
- `409 REVIEW_STALE`: அட்டையில் சேமிக்கப்பட்ட மீள்பயிற்சி நேரம் தற்போதைய சேவையக நேரத்துக்குச் சமமாகவோ அதற்குப் பின்னதாகவோ உள்ளது; வேறோர் அட்டையை மீள்பயிற்சி செய்யுங்கள்.
- `400 REVIEW_INPUT_INVALID`: ஓர் அளவுரு விடுபட்டுள்ளது, செல்லாதது அல்லது ஆதரிக்கப்படாதது; `deckId` உடன் சேர்க்கப்பட்ட `tags`, பணியிடம் பயன்படுத்தாத ஒரு குறிச்சொல் ஆகியவையும் இதில் அடங்கும்.

சமர்ப்பிப்புக்கு ஓர் எடுத்துக்காட்டு:

```bash
curl -X POST https://api.nibomo.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 இல் தனி API களும் உள்ளன, ஆனால் அவை வெளிப்புற முகவர்களுக்கான முதன்மை ஒப்பந்தம் அல்ல:

- உலாவி ஓட்டங்கள் பகிரப்பட்ட டொமைன் குக்கீகளையும் CSRF பாதுகாப்பையும் பயன்படுத்துகின்றன
- இணையம் இல்லாமல் இயங்குவதை முதன்மையாகக் கொண்ட கிளையண்டுகள் `/v1/workspaces/{workspaceId}/sync/push`, `/v1/workspaces/{workspaceId}/sync/pull` இன் கீழ் செயல்படுத்தப்பட்ட ஒத்திசைவு வழிகளைப் பயன்படுத்துகின்றன
- ஒத்திசைவு வழிகள் வெளிப்புற முகவர் இடைமுகத்திலிருந்து தனியானவை

---
*[இந்தப் பக்கத்தின் வடிவமைக்கப்பட்ட HTML பதிப்பைப் பாருங்கள்](<https://nibomo.com/ta/docs/api/>)*

*AI முகவர்கள் `GET https://api.nibomo.com/v1/` இல் தொடங்கி இந்தச் சேவையில் பயனருக்குக் கணக்கை உருவாக்க முடியும். அமைத்த பிறகு `https://mcp.nibomo.com/mcp` இல் MCP வழியாகவும் இணைய முடியும்.*

*குறிப்பு: https://nibomo.com இல் உள்ள எந்த URL இன் இறுதியிலும் `.md` சேர்த்தால் அந்தப் பக்கத்தின் சுத்தமான Markdown பதிப்பு கிடைக்கும்.*