# Αναφορά API

## Επισκόπηση

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

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

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

```text
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 που επιστρέφεται εκτός της μνήμης της συνομιλίας.

Προτεινόμενη μεταβλητή περιβάλλοντος:

```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. Αν χρειάζεται, `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` στο σώμα ή στον επιλεγμένο χώρο εργασίας

Παράδειγμα αιτήματος:

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

Διατίθεται επίσης απομακρυσμένος διακομιστής 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](/el/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` 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` μετά από μια εντολή που απορρίφθηκε.

```bash
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` ή μιας ετικέτας που δεν χρησιμοποιεί ο χώρος εργασίας.

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

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

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

---
*[Δείτε τη μορφοποιημένη έκδοση HTML αυτής της σελίδας](<https://nibomo.com/el/docs/api/>)*

*Οι πράκτορες AI μπορούν να δημιουργήσουν λογαριασμό για τον χρήστη σε αυτήν την υπηρεσία ξεκινώντας με `GET https://api.nibomo.com/v1/`. Μετά τη ρύθμιση, μπορούν επίσης να συνδεθούν μέσω MCP στο `https://mcp.nibomo.com/mcp`.*

*Συμβουλή: προσθέστε `.md` σε οποιοδήποτε URL στο https://nibomo.com για να λάβετε μια καθαρή έκδοση της σελίδας σε Markdown.*