ΣύνδεσηΔωρεάν εγγραφή

Αναφορά API

Επισκόπηση

Αυτή η σελίδα τεκμηριώνει το τρέχον συμβόλαιο του Nibomo για εξωτερικούς πράκτορες AI.

Αν το πρόγραμμα-πελάτης σας υποστηρίζει MCP, ο connector MCP είναι ο απλούστερος τρόπος σύνδεσης και βασίζεται στην ίδια επιφάνεια δεδομένων. Αυτή η σελίδα τεκμηριώνει το συμβόλαιο HTTP για ανακάλυψη, SQL, οδηγούς και επαναλήψεις που χρησιμοποιούν οι πράκτορες CLI.

Ξεκινήστε από το επίσημο σημείο εισόδου ανακάλυψης:

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

Το ίδιο περιεχόμενο ανακάλυψης είναι διαθέσιμο και στο GET /v1/agent, αλλά το /v1/ είναι το κύριο δημόσιο σημείο εισόδου.

Η απάντηση ανακάλυψης εξηγεί σε έναν πράκτορα πώς να:

  • ξεκινήσει τη σύνδεση με OTP μέσω email
  • ανταλλάξει τον κωδικό OTP με ένα μακροχρόνιο κλειδί API
  • φορτώσει τα στοιχεία του λογαριασμού
  • δημιουργήσει ή επιλέξει έναν χώρο εργασίας
  • συνεχίσει μέσω της δημοσιευμένης επιφάνειας SQL
  • ανακτήσει οδηγούς αναφοράς και κάνει επανάληψη καρτών μία προς μία

Ανακάλυψη κατά την εκτέλεση και πηγαίος κώδικας

Το OpenAPI δεν είναι διαθέσιμο. Οι τέσσερις παλιές διευθύνσεις προδιαγραφών παρακάτω επιστρέφουν πλέον την ίδια ειδοποίηση ανακάλυψης σε JSON με "openapiAvailable": false αντί για σχήμα:

  • 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. Στείλτε το email του χρήστη στο send-code.
  3. Διαβάστε το otpSessionToken από την απάντηση.
  4. Ζητήστε από τον χρήστη τον πιο πρόσφατο 8ψήφιο κωδικό από το email.
  5. Καλέστε το verify-code με code, otpSessionToken και label.
  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. Αν χρειάζεται, POST /v1/agent/workspaces με {"name":"Personal"}
  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 και επαναλήψεων δέχονται επίσης προαιρετικό workspaceId στο σώμα JSON. Με αυτό, μία μεμονωμένη κλήση απευθύνεται στον συγκεκριμένο χώρο εργασίας χωρίς να αλλάζει η επιλογή· παραλείψτε το για να χρησιμοποιηθεί ο επιλεγμένος χώρος εργασίας. Αν δεν υπάρχει ούτε επιλογή ούτε 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'\''"
  }'

Διατίθεται επίσης απομακρυσμένος διακομιστής MCP στο https://mcp.nibomo.com/mcp, με OAuth 2.1 (Dynamic Client Registration + PKCE). Παρέχει τον ίδιο διαχωρισμό SQL, με τα sql_query (αυστηρά μόνο ανάγνωση) και sql_execute (εγγραφή), καθώς και τα list_workspaces, get_guide και τα εργαλεία επανάληψης next_review_card, reveal_answer και submit_review· δείτε τον connector MCP.

Ασφάλεια και εύρος πρόσβασης

Η επιφάνεια SQL είναι μια περιορισμένη διάλεκτος που επιβάλλεται από τον συντακτικό αναλυτή, όχι ακατέργαστη PostgreSQL. Οι δικλίδες ασφαλείας είναι:

  • Κλειστή λίστα επιτρεπόμενων εντολών: μόνο SHOW TABLES, DESCRIBE, SHOW COLUMNS και SELECT για αναγνώσεις, και INSERT, UPDATE και DELETE για εγγραφές. Οτιδήποτε άλλο απορρίπτεται κατά τη συντακτική ανάλυση.
  • Περιορισμένοι πόροι: οι εντολές μπορούν να αγγίζουν μόνο τους πόρους workspace, cards, decks και review_events.
  • Περιορισμός ανά χώρο εργασίας: κάθε εντολή περιορίζεται σε έναν χώρο εργασίας στον οποίο έχετε πρόσβαση, είτε σε αυτόν που ορίζει το workspaceId στο σώμα του αιτήματος είτε στον επιλεγμένο χώρο εργασίας σας, χωρίς πρόσβαση σε δεδομένα άλλων μισθωτών.
  • Αυστηρά σώματα αιτημάτων: οι διαδρομές SQL και επαναλήψεων απορρίπτουν άγνωστο πεδίο στο σώμα, οπότε ένα ανορθόγραφο workspaceId αποτυγχάνει αντί να εκτελεστεί στον επιλεγμένο χώρο εργασίας.
  • Όρια: έως 100 γραμμές ανά εντολή, έως 50 εντολές ανά δέσμη και όριο αποτελέσματος περίπου 12k tokens. Οι δέσμες τροποποιήσεων εφαρμόζονται ατομικά.
  • Διαχωρισμός ανάγνωσης/εγγραφής: τα 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 της κάρτας. Δέχονται τα ίδια ορίσματα JSON με τα εργαλεία επανάληψης του MCP:

  • Το POST /v1/agent/reviews/next επιστρέφει card με cardId και frontText, ή card: null όταν δεν υπάρχει τίποτα προς επανάληψη. Τα προαιρετικά tags (αρκεί μία από τις ετικέτες) ή deckId περιορίζουν την ουρά, αλλά ποτέ και τα δύο μαζί· ένα αίτημα χωρίς σώμα είναι έγκυρο.
  • Το POST /v1/agent/reviews/reveal απαιτεί cardId και επιστρέφει το backText της κάρτας.
  • Το POST /v1/agent/reviews/submit απαιτεί cardId, ένα UUID reviewId που δημιουργείται από το πρόγραμμα-πελάτη, ένα rating με τιμή Again, Hard, Good ή Easy και τη ζώνη ώρας 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: ένα όρισμα λείπει, δεν είναι έγκυρο ή δεν υποστηρίζεται, συμπεριλαμβανομένου του συνδυασμού tags με deckId ή μιας ετικέτας που δεν χρησιμοποιεί ο χώρος εργασίας.

Παράδειγμα υποβολής:

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 για προγράμματα-πελάτες που χρησιμοποιούν άνθρωποι και για συγχρονισμό με προτεραιότητα στη λειτουργία εκτός σύνδεσης, αλλά δεν αποτελούν το κύριο συμβόλαιο για εξωτερικούς πράκτορες:

  • οι ροές του προγράμματος περιήγησης χρησιμοποιούν cookies κοινού τομέα μαζί με προστασία CSRF
  • τα προγράμματα-πελάτες με προτεραιότητα στη λειτουργία εκτός σύνδεσης χρησιμοποιούν τις υλοποιημένες διαδρομές συγχρονισμού /v1/workspaces/{workspaceId}/sync/push και /v1/workspaces/{workspaceId}/sync/pull
  • οι διαδρομές συγχρονισμού είναι ξεχωριστές από την επιφάνεια για εξωτερικούς πράκτορες