API குறிப்பு

கண்ணோட்டம்

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

உங்கள் கிளையண்ட் MCP ஐ ஆதரித்தால், இணைவதற்கான மிக எளிய வழி MCP இணைப்பான்; அது இதே தரவு இடைமுகத்தை உள்ளடக்கியுள்ளது. CLI முகவர்கள் பயன்படுத்தும் HTTP கண்டறிதல், SQL, வழிகாட்டி, மீள்பயிற்சி ஒப்பந்தத்தை இந்தப் பக்கம் விவரிக்கிறது.

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

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 விசையை அரட்டை நினைவகத்துக்கு வெளியே சேமித்து வையுங்கள்.

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

export FLASHCARDS_OPEN_SOURCE_API_KEY="fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS"

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

Authorization: ApiKey <key>

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

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

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

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, அல்லது தேர்ந்தெடுக்கப்பட்ட பணியிடம்

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

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

அட்டை வினவலுக்கு ஓர் எடுத்துக்காட்டு:

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

மாற்றத்துக்கு ஓர் எடுத்துக்காட்டு:

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 இணைப்பான் ஐப் பாருங்கள்.

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

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 ஐ மீண்டும் படியுங்கள்.

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, பணியிடம் பயன்படுத்தாத ஒரு குறிச்சொல் ஆகியவையும் இதில் அடங்கும்.

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

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 இன் கீழ் செயல்படுத்தப்பட்ட ஒத்திசைவு வழிகளைப் பயன்படுத்துகின்றன
• ஒத்திசைவு வழிகள் வெளிப்புற முகவர் இடைமுகத்திலிருந்து தனியானவை