AI Agents API

Το AI Agents API διαχειρίζεται generate-only AI agents: επαναχρησιμοποιήσιμα αντικείμενα που διαβάζουν ένα οριοθετημένο πλαίσιο (context) και παράγουν επικυρωμένη δομημένη έξοδο, πάνω στην οποία ενεργούν τα journeys και τα catalog jobs σας. Ένας agent δεν έχει εργαλεία ούτε ενέργειες - δεν στέλνει, δεν διακλαδώνει και δεν γράφει ποτέ μόνος του. Δείτε τον οδηγό AI Agents στο dashboard για τις έννοιες.

Αυτό το API αντικατοπτρίζει την επιφάνεια Ρυθμίσεις → AI Agents του dashboard. Χρησιμοποιήστε το για να αυτοματοποιήσετε τη δημιουργία agents, να καταχωρίσετε κλειδιά παρόχων bring-your-own (BYO), να κάνετε dry-run έναν agent σε δείγμα context και να διαβάσετε ίχνη εκτελέσεων (run traces).

Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com/api - δείτε Επισκόπηση API.

Έλεγχος ταυτότητας

Κάθε αίτημα ελέγχεται είτε με κλειδί API που φέρει το σχετικό scope είτε με συνεδρία dashboard (JWT). Οι agents ισχύουν ανά χώρο εργασίας - ένα κλειδί βλέπει και επεξεργάζεται μόνο τους agents του δικού του χώρου εργασίας.

Authorization: Bearer your_api_key_or_jwt
Content-Type: application/json

Scopes ανά endpoint

Τα endpoints ανάγνωσης χρειάζονται ai_agents:read· τα endpoints εγγραφής χρειάζονται ai_agents:write. Οι συνεδρίες dashboard μπορούν εναλλακτικά να χρησιμοποιήσουν το role scope settings:read / settings:write που μοιράζονται οι επιφάνειες AI - οποιοδήποτε από τα δύο παρέχει πρόσβαση.

Endpoint	Scope
`POST /ai-agents`	`ai_agents:write` (ή `settings:write`)
`GET /ai-agents`	`ai_agents:read` (ή `settings:read`)
`GET /ai-agents/{id}`	`ai_agents:read` (ή `settings:read`)
`PUT /ai-agents/{id}`	`ai_agents:write` (ή `settings:write`)
`POST /ai-agents/{id}/archive`	`ai_agents:write` (ή `settings:write`)
`DELETE /ai-agents/{id}`	`ai_agents:write` (ή `settings:write`)
`POST /ai-agents/{id}/test`	`ai_agents:write` (ή `settings:write`)
`GET /ai-agents/{id}/runs`	`ai_agents:read` (ή `settings:read`)
`GET /ai-agents/provider-keys`	`ai_agents:read` (ή `settings:read`)
`PUT /ai-agents/provider-keys/{provider}`	`ai_agents:write` (ή `settings:write`)
`DELETE /ai-agents/provider-keys/{provider}`	`ai_agents:write` (ή `settings:write`)
`PUT /ai-agents/provider-keys/{provider}/assistant`	`ai_agents:write` (ή `settings:write`)
`POST /ai-agents/enrichment/run`	`ai_agents:write` (ή `settings:write`)
`GET /ai-agents/enrichment/jobs`	`ai_agents:read` (ή `settings:read`)
`GET /ai-agents/enrichment/jobs/{jobId}`	`ai_agents:read` (ή `settings:read`)

Βασικές έννοιες

Λειτουργία μοντέλου και πάροχος

Το modelMode ενός agent είναι είτε managed είτε byo:

managed - το φιλοξενούμενο μοντέλο Claude του Joryio. Ο provider είναι joryio. Χρεώνεται ως μία μονάδα (credit) ανά εκτέλεση.
byo - το δικό σας κλειδί. Ο provider είναι ένας από τους anthropic, openai, google, azure, bedrock. Καταχωρίστε πρώτα το κλειδί μέσω των endpoints provider-keys. Χρεώνεται με μικρή σταθερή αμοιβή πλατφόρμας ανά εκτέλεση.

Σχήμα εξόδου

Το outputSchema.type είναι string, number, boolean ή json. Για json, δώστε έναν πίνακα fields από { name, type, description? }, όπου το type είναι πρωτογενής τύπος. Ορίστε includeExplanation: true για να καταγράφεται ο συλλογισμός του μοντέλου σε ένα πεδίο explanation.

Επιλογείς context

Το contextSelectors είναι opt-in - ο agent δεν διαβάζει τίποτα αν δεν αναφέρεται ρητά: attributeKeys, segmentIds, catalogFields, requiredCatalogFields (πεδία καταλόγου που πρέπει να υπάρχουν - ο εμπλουτισμός παραλείπει, και δεν χρεώνει ποτέ, γραμμή στην οποία λείπει κάποιο), includeBrandVoice, includeRecentEngagement και maskPiiKeys (κλειδιά που καλύπτονται πριν φτάσει το context στο μοντέλο· τα PII που είναι επισημασμένα καθολικά στα Προσαρμοσμένα γνωρίσματα καλύπτονται επίσης πάντα).

Αποτελέσματα εκτελέσεων

Κάθε εκτέλεση καταλήγει σε ένα αποτέλεσμα: success, fallback, timeout, rate_limited, invalid_config ή budget_exceeded. Δείτε το συμβόλαιο σφαλμάτων.

Δημιουργία agent

Endpoint

POST /ai-agents

Σώμα αιτήματος

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`name`	string	Ναι	Ευανάγνωστο όνομα (μέγιστο 200).
`description`	string	Όχι	Προαιρετική περιγραφή (μέγιστο 1000).
`tags`	string[]	Όχι	Ονόματα ετικετών του χώρου εργασίας για φιλτράρισμα/οργάνωση (καθεμία μέγιστο 60· έως 50).
`instructions`	string	Ναι	Στόχος / οδηγίες συστήματος, με πρότυπα Liquid (μέγιστο 20000).
`modelMode`	string	Όχι	`managed` (προεπιλογή) ή `byo`.
`provider`	string	Όχι	`joryio`, `anthropic`, `openai`, `google`, `azure`, `bedrock`. Προεπιλογή `joryio` για managed, `anthropic` για BYO.
`model`	string	Όχι	Συγκεκριμένο id μοντέλου (π.χ. `claude-opus-4-8`).
`thinkingLevel`	string	Όχι	`minimal`, `low`, `medium` ή `high`.
`contextSelectors`	object	Όχι	Τι μπορεί να διαβάσει ο agent (opt-in).
`outputSchema`	object	Όχι	Η μορφή εξόδου στην οποία περιορίζεται το μοντέλο. Προεπιλογή `{ "type": "string" }`.
`task`	string	Όχι	`write` (προεπιλογή) ή `classify`: μία ετικέτα από λίστα· η διαδρομή δρομολογείται σε αυτήν.
`classification`	object	Όχι	Για `classify`: `{ "labels": [{ "id"?, "name", "description"? }], "unsureBelow"? }`. Τα ids ανατίθενται κατά την αποθήκευση όταν λείπουν· έως 255 ετικέτες· το `unsure` είναι δεσμευμένο.
`fallbackValue`	any	Όχι	Τιμή που επιστρέφεται όταν μια εκτέλεση αποτύχει.
`dailyCap`	integer	Όχι	Ημερήσιο όριο κλήσεων ανά agent (προεπιλογή 250000, ελάχιστο 0).
`guardrails`	object	Όχι	`maxOutputTokens`, `timeoutMs`, `retryOnTransient`.

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

curl -X POST https://api-eu1.joryio.com/api/ai-agents \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cart subject-line writer",
    "instructions": "Write a short, upbeat email subject line for the abandoned cart. Max 60 characters.",
    "modelMode": "managed",
    "contextSelectors": {
      "attributeKeys": ["first_name", "cart_total"],
      "includeBrandVoice": true
    },
    "outputSchema": {
      "type": "json",
      "fields": [{ "name": "subject", "type": "string" }],
      "includeExplanation": true
    },
    "fallbackValue": { "subject": "You left something behind" },
    "dailyCap": 50000,
    "guardrails": { "timeoutMs": 20000, "retryOnTransient": true }
  }'

Απόκριση

{
  "id": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "organizationId": "org_123",
  "workspaceId": "ws_456",
  "name": "Cart subject-line writer",
  "description": null,
  "status": "active",
  "instructions": "Write a short, upbeat email subject line for the abandoned cart. Max 60 characters.",
  "modelMode": "managed",
  "provider": "joryio",
  "model": "",
  "thinkingLevel": null,
  "contextSelectors": {
    "attributeKeys": ["first_name", "cart_total"],
    "includeBrandVoice": true
  },
  "outputSchema": {
    "type": "json",
    "fields": [{ "name": "subject", "type": "string" }],
    "includeExplanation": true
  },
  "fallbackValue": { "subject": "You left something behind" },
  "dailyCap": 50000,
  "guardrails": { "timeoutMs": 20000, "retryOnTransient": true },
  "createdBy": "user_789",
  "createdAt": "2026-07-11T09:00:00.000Z",
  "updatedAt": "2026-07-11T09:00:00.000Z"
}

Λίστα agents

Endpoint

GET /ai-agents

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`status`	string	-	Προαιρετικό φίλτρο: `active` ή `archived`.

Οι agents επιστρέφονται με πρώτους τους πιο πρόσφατα ενημερωμένους.

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

curl -X GET "https://api-eu1.joryio.com/api/ai-agents?status=active" \
  -H "Authorization: Bearer your_api_key"

Απόκριση

[
  {
    "id": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "name": "Cart subject-line writer",
    "status": "active",
    "modelMode": "managed",
    "provider": "joryio",
    "dailyCap": 50000,
    "updatedAt": "2026-07-11T09:00:00.000Z"
  }
]

Λήψη ενός agent

Endpoint

GET /ai-agents/{id}

Η παράμετρος διαδρομής {id} είναι το UUID του agent.

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

curl -X GET https://api-eu1.joryio.com/api/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer your_api_key"

Επιστρέφει το πλήρες αντικείμενο agent (ίδια μορφή με την απόκριση δημιουργίας). Επιστρέφει 404 αν ο agent δεν υπάρχει σε αυτόν τον χώρο εργασίας.

Ενημέρωση agent

Endpoint

PUT /ai-agents/{id}

Μερική ενημέρωση - στείλτε μόνο τα πεδία που θέλετε να αλλάξετε. Γίνονται δεκτά όλα τα πεδία δημιουργίας, συν το status (active ή archived).

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

curl -X PUT https://api-eu1.joryio.com/api/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyCap": 100000,
    "guardrails": { "timeoutMs": 15000, "retryOnTransient": false }
  }'

Επιστρέφει το ενημερωμένο αντικείμενο agent.

Αρχειοθέτηση agent

Ήπια αρχειοθέτηση ενός agent: το status γίνεται archived, κάτι που σταματά τη χρήση αλλά διατηρεί το ιστορικό εκτελέσεών του.

Endpoint

POST /ai-agents/{id}/archive

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

curl -X POST https://api-eu1.joryio.com/api/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/archive \
  -H "Authorization: Bearer your_api_key"

Επιστρέφει το αρχειοθετημένο αντικείμενο agent ("status": "archived").

Διαγραφή agent

Endpoint

DELETE /ai-agents/{id}

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

curl -X DELETE https://api-eu1.joryio.com/api/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer your_api_key"

Απόκριση

{ "success": true }

Δοκιμή (προεπισκόπηση) agent

Εκτελέστε τον agent δοκιμαστικά (dry-run) σε ένα δείγμα context που παρέχετε. Η εκτέλεση χρησιμοποιεί νέο run key και surface test, οπότε δεν προσμετράται ποτέ σε πραγματικό journey. Επιστρέφει μόνο το αποτέλεσμα προς τον πελάτη - χωρίς πεδία μέτρησης.

Endpoint

POST /ai-agents/{id}/test

Σώμα αιτήματος

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`attributes`	object	Όχι	Δείγμα γνωρισμάτων επαφής με κλειδί το όνομα.
`segmentMemberships`	string[]	Όχι	Δείγμα συμμετοχών σε τμήματα.
`catalogRecord`	object	Όχι	Δείγμα εγγραφής καταλόγου/οντότητας προς εμπλουτισμό.
`engagement`	object	Όχι	Δείγμα σύνοψης πρόσφατης αλληλεπίδρασης.

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

curl -X POST https://api-eu1.joryio.com/api/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/test \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": { "first_name": "Dana", "cart_total": 249.90 },
    "segmentMemberships": ["vip"]
  }'

Απόκριση

{
  "outcome": "success",
  "output": { "subject": "Dana, your cart misses you" },
  "explanation": "Used the first name and an upbeat tone from the brand voice."
}

Το outcome είναι ένα από τα success, fallback, timeout, rate_limited, invalid_config ή budget_exceeded. Το explanation είναι null όταν το σχήμα δεν περιλαμβάνει explanation.

Λίστα εκτελέσεων agent

Επιστρέφει τα πρόσφατα ίχνη εκτελέσεων για έναν agent, με τα νεότερα πρώτα.

Endpoint

GET /ai-agents/{id}/runs

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`limit`	number	`50`	Γραμμές που επιστρέφονται (1–200).

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

curl -X GET "https://api-eu1.joryio.com/api/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b/runs?limit=25" \
  -H "Authorization: Bearer your_api_key"

Απόκριση

{
  "rows": [
    {
      "id": "run_abc123",
      "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
      "surface": "journey",
      "provider": "joryio",
      "model": "claude-opus-4-8",
      "modelMode": "managed",
      "inputTokens": 420,
      "outputTokens": 28,
      "latencyMs": 1180,
      "outcome": "success",
      "output": { "subject": "Dana, your cart misses you" },
      "explanation": "Used the first name and an upbeat tone.",
      "error": null,
      "createdAt": "2026-07-11T09:05:00.000Z"
    }
  ]
}

Το ίχνος αποθηκεύει μόνο αναφορές εισόδου (ποια εκτέλεση, κόμβος, εγγραφή ή χρήστης) - ποτέ το ακατέργαστο κείμενο του prompt.

Λίστα κλειδιών παρόχων BYO

Επιστρέφει τα καταχωρισμένα κλειδιά παρόχων bring-your-own του χώρου εργασίας. Οι τιμές διαπιστευτηρίων δεν επιστρέφονται ποτέ - το αντικείμενο credentials είναι πάντα κενό.

Endpoint

GET /ai-agents/provider-keys

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

curl -X GET https://api-eu1.joryio.com/api/ai-agents/provider-keys \
  -H "Authorization: Bearer your_api_key"

Απόκριση

[
  {
    "id": "key_111",
    "provider": "openai",
    "credentials": {},
    "label": "Production OpenAI",
    "status": "active",
    "lastUsedAt": "2026-07-11T08:00:00.000Z",
    "lastError": null,
    "createdAt": "2026-07-01T00:00:00.000Z",
    "updatedAt": "2026-07-11T08:00:00.000Z"
  }
]

Upsert κλειδιού παρόχου BYO

Δημιουργεί ή αντικαθιστά το κλειδί ενός παρόχου. Υπάρχει ένα κλειδί ανά (workspace, provider). Ο managed πάροχος joryio δεν δέχεται κλειδί και απορρίπτεται.

Endpoint

PUT /ai-agents/provider-keys/{provider}

Η παράμετρος διαδρομής {provider} είναι μία από τις anthropic, openai, google, azure, bedrock.

Σώμα αιτήματος

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`credentials`	object	Ναι	Τιμές διαπιστευτηρίων ανά πάροχο (π.χ. `{ "apiKey": "..." }`· Azure/Bedrock δέχονται περισσότερες). Κρυπτογραφούνται σε ηρεμία, δεν επιστρέφονται ποτέ.
`label`	string	Όχι	Προαιρετική ετικέτα (μέγιστο 120).

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

curl -X PUT https://api-eu1.joryio.com/api/ai-agents/provider-keys/openai \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "sk-your-openai-key" },
    "label": "Production OpenAI"
  }'

Απόκριση

{
  "id": "key_111",
  "provider": "openai",
  "credentials": {},
  "label": "Production OpenAI",
  "status": "active",
  "lastUsedAt": null,
  "lastError": null,
  "createdAt": "2026-07-11T09:10:00.000Z",
  "updatedAt": "2026-07-11T09:10:00.000Z"
}

Δρομολόγηση του βοηθού και της δημιουργίας περιεχομένου μέσω κλειδιού

Κάντε ένα από τα κλειδιά του workspace το κλειδί που εξυπηρετεί τον Joryio Assistant και κάθε λειτουργία δημιουργίας περιεχομένου, ή επιστρέψτε τα στο κλειδί πλατφόρμας της Joryio. Το πολύ ένα κλειδί ανά workspace φέρει τη σήμανση· η ενεργοποίησή της σε δεύτερο κλειδί τη μεταφέρει. Οι εκτελέσεις με το κλειδί σας χρεώνονται μια μικρή αμοιβή πλατφόρμας ανά χρήση (generation, assistant_turn) από τον τιμοκατάλογο αντί για το κόστος των tokens. Ο βοηθός τρέχει μόνο με κλειδί Anthropic· με άλλον πάροχο παραμένει στο κλειδί πλατφόρμας και δρομολογείται μόνο η δημιουργία.

Endpoint

PUT /ai-agents/provider-keys/{provider}/assistant

Σώμα αιτήματος

Πεδίο	Τύπος	Υποχρεωτικό	Περιγραφή
`enabled`	boolean	✓	`true` για δρομολόγηση μέσω αυτού του κλειδιού, `false` για επιστροφή στο κλειδί πλατφόρμας.

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

curl -X PUT https://api-eu1.joryio.com/api/ai-agents/provider-keys/anthropic/assistant \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Απόκριση

Η γραμμή του κλειδιού, χωρίς διαπιστευτήρια, με το useForAssistant ορισμένο:

{
  "id": "key_111",
  "provider": "anthropic",
  "credentials": {},
  "label": "Production",
  "status": "active",
  "useForAssistant": true,
  "updatedAt": "2026-09-10T08:00:00.000Z"
}

Σφάλματα: 404 όταν δεν υπάρχει αποθηκευμένο κλειδί για αυτόν τον πάροχο στο workspace· 400 όταν το κλειδί είναι απενεργοποιημένο ή ο πάροχος είναι joryio.

Διαγραφή κλειδιού παρόχου BYO

Endpoint

DELETE /ai-agents/provider-keys/{provider}

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

curl -X DELETE https://api-eu1.joryio.com/api/ai-agents/provider-keys/openai \
  -H "Authorization: Bearer your_api_key"

Απόκριση

{ "success": true }

Εκτέλεση εμπλουτισμού καταλόγου

Εκτελέστε έναν generate-only agent πάνω στις εγγραφές μιας προσαρμοσμένης οντότητας και γράψτε κάθε έξοδο σε ένα πεδίο-στόχο - περιγραφές προϊόντων, ετικέτες, μια κανονικοποιημένη κατηγορία. Το job είναι ασύγχρονο/σε ουρά: αυτό το endpoint δημιουργεί ένα job (status: queued), βάζει τη δουλειά στην ουρά και επιστρέφει αμέσως - ένας μεγάλος κατάλογος (έως 100k γραμμές) επεξεργάζεται εκτός της διαδρομής του αιτήματος. Κάντε poll το Λήψη ενός job εμπλουτισμού για την πρόοδο. Το job είναι idempotent ανά εγγραφή (το run key είναι jobId:recordId), οπότε ένα επαναληφθέν job δεν ξαναχρεώνει ποτέ μια ήδη εμπλουτισμένη εγγραφή.

Endpoint

POST /ai-agents/enrichment/run

Σώμα αιτήματος

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`agentId`	string	Ναι	Ο agent που θα εκτελεστεί (πρέπει να είναι ενεργός agent σε αυτόν τον χώρο εργασίας).
`entityDefinitionId`	string	Ναι	Ο ορισμός προσαρμοσμένης οντότητας του οποίου οι εγγραφές εμπλουτίζονται.
`targetField`	string	Ναι	Το πεδίο εγγραφής στο οποίο γράφεται η έξοδος (πρέπει να είναι δηλωμένο πεδίο της οντότητας).
`filter`	object	Όχι	Προαιρετικό φίλτρο τύπου MongoDB που περιορίζει ποιες εγγραφές εμπλουτίζονται.
`limit`	integer	Όχι	Μέγιστες εγγραφές προς επεξεργασία σε αυτό το job (έως 100000, με αυστηρό όριο στον διακομιστή).

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

curl -X POST https://api-eu1.joryio.com/api/ai-agents/enrichment/run \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "entityDefinitionId": "product",
    "targetField": "ai_description",
    "filter": { "category": "shoes" },
    "limit": 200
  }'

Απόκριση

Το job που μπήκε στην ουρά. Το status είναι queued τη στιγμή της υποβολής· οι μετρήσεις συμπληρώνονται καθώς το job εκτελείται. Κάντε poll το Λήψη ενός job εμπλουτισμού για να το παρακολουθήσετε μέχρι την ολοκλήρωση.

{
  "jobId": "job_9a8b7c",
  "status": "queued",
  "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "entityDefinitionId": "product",
  "targetField": "ai_description",
  "counts": {
    "total": 200,
    "processed": 0,
    "succeeded": 0,
    "failed": 0,
    "skipped": 0
  },
  "error": null,
  "createdAt": "2026-07-11T09:20:00.000Z",
  "updatedAt": "2026-07-11T09:20:00.000Z"
}

Λήψη ενός job εμπλουτισμού

Κάντε poll την κατάσταση και τις μετρήσεις ενός job εμπλουτισμού.

Endpoint

GET /ai-agents/enrichment/jobs/{jobId}

Η παράμετρος διαδρομής {jobId} είναι το id του job που επιστρέφεται από την Εκτέλεση εμπλουτισμού καταλόγου.

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

curl -X GET https://api-eu1.joryio.com/api/ai-agents/enrichment/jobs/job_9a8b7c \
  -H "Authorization: Bearer your_api_key"

Απόκριση

Το status είναι ένα από τα queued, running, completed ή failed. Το error συμπληρώνεται μόνο όταν το job απέτυχε ως σύνολο.

{
  "jobId": "job_9a8b7c",
  "status": "completed",
  "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "entityDefinitionId": "product",
  "targetField": "ai_description",
  "counts": {
    "total": 200,
    "processed": 200,
    "succeeded": 194,
    "failed": 2,
    "skipped": 4
  },
  "error": null,
  "createdAt": "2026-07-11T09:20:00.000Z",
  "updatedAt": "2026-07-11T09:22:30.000Z"
}

Επιστρέφει 404 αν το job δεν υπάρχει σε αυτόν τον χώρο εργασίας. Χρειάζεται ai_agents:read (ή settings:read).

Λίστα jobs εμπλουτισμού

Επιστρέφει τα πρόσφατα jobs εμπλουτισμού του χώρου εργασίας, με τα νεότερα πρώτα - για πρόοδο και ιστορικό.

Endpoint

GET /ai-agents/enrichment/jobs

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`limit`	integer	`20`	Γραμμές που επιστρέφονται (νεότερες πρώτα).

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

curl -X GET "https://api-eu1.joryio.com/api/ai-agents/enrichment/jobs?limit=20" \
  -H "Authorization: Bearer your_api_key"

Απόκριση

Πίνακας από jobs, καθένα στην ίδια μορφή με το Λήψη ενός job εμπλουτισμού.

[
  {
    "jobId": "job_9a8b7c",
    "status": "completed",
    "agentId": "8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "entityDefinitionId": "product",
    "targetField": "ai_description",
    "counts": {
      "total": 200,
      "processed": 200,
      "succeeded": 194,
      "failed": 2,
      "skipped": 4
    },
    "error": null,
    "createdAt": "2026-07-11T09:20:00.000Z",
    "updatedAt": "2026-07-11T09:22:30.000Z"
  }
]

Χρειάζεται ai_agents:read (ή settings:read).

Αποκρίσεις σφαλμάτων

Όλα τα σφάλματα μοιράζονται την τυπική μορφή - δεν υπάρχει ξεχωριστό μηχαναγνώσιμο λεξιλόγιο κωδικών σφαλμάτων· χρησιμοποιήστε την κατάσταση HTTP μαζί με το πεδίο message. Δείτε Απόκριση σφάλματος στην Επισκόπηση API.

{
  "statusCode": 404,
  "message": "AI agent 8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b not found",
  "timestamp": "2026-07-11T09:20:00.000Z",
  "path": "/ai-agents/8f0e2b3a-1c4d-4e5f-9a0b-1c2d3e4f5a6b"
}

Αξιοσημείωτες καταστάσεις σε αυτό το API:

Κατάσταση	Πότε
`400`	Μη έγκυρη ρύθμιση - π.χ. `"instructions are required"`, `"No BYO key configured for provider 'openai' - add a key before using it in BYO mode"`, `"status must be one of: active, draft, archived"`
`401`	Κλειδί API που λείπει ή είναι μη έγκυρο
`403`	Το κλειδί δεν έχει το απαιτούμενο scope `ai_agents:read` / `ai_agents:write`
`404`	Δεν βρέθηκε agent, job εμπλουτισμού ή κλειδί παρόχου BYO

Επόμενα βήματα

Τιμολόγηση εκτελέσεων

Endpoint

GET /ai-agents/pricing

Εμβέλεια: ai_agents:read. Τιμή ανά εκτέλεση σε micros (1.000.000 micros = 1 USD) για κάθε εργασία και τρόπο φιλοξενίας, από τον τιμοκατάλογο, με τις ίδιες εφεδρικές τιμές που χρεώνει ο runner. Ο επεξεργαστής το δείχνει ως «περίπου X ανά 1.000 εκτελέσεις».

Απόκριση

{
  "unit": "micros",
  "perRun": {
    "write":    { "managed": 2000, "byo": 500 },
    "classify": { "managed": 1000, "byo": 250 }
  }
}

Μια εκτέλεση ταξινόμησης απαντά { "label": "<label id>" | "unsure", "confidence": 0..1 } και ο κόμβος διαδρομής δρομολογεί στο id της ετικέτας· η γραμμή εκτέλεσης καταγράφει το labelSetVersion, το hash περιεχομένου του συνόλου ετικετών στο οποίο απάντησε.

Έλεγχος ταυτότητας​

Scopes ανά endpoint​

Βασικές έννοιες​

Λειτουργία μοντέλου και πάροχος​

Σχήμα εξόδου​

Επιλογείς context​

Αποτελέσματα εκτελέσεων​

Δημιουργία agent​

Endpoint​

Σώμα αιτήματος​

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

Απόκριση​

Λίστα agents​

Endpoint​

Παράμετροι query​

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

Απόκριση​

Λήψη ενός agent​

Endpoint​

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

Ενημέρωση agent​

Endpoint​

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

Αρχειοθέτηση agent​

Endpoint​

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

Διαγραφή agent​

Endpoint​

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

Απόκριση​

Δοκιμή (προεπισκόπηση) agent​

Endpoint​

Σώμα αιτήματος​

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

Απόκριση​

Λίστα εκτελέσεων agent​

Endpoint​

Παράμετροι query​

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

Απόκριση​

Λίστα κλειδιών παρόχων BYO​

Endpoint​

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

Απόκριση​

Upsert κλειδιού παρόχου BYO​

Endpoint​

Σώμα αιτήματος​

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

Απόκριση​

Δρομολόγηση του βοηθού και της δημιουργίας περιεχομένου μέσω κλειδιού​

Endpoint​

Σώμα αιτήματος​

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

Απόκριση​

Διαγραφή κλειδιού παρόχου BYO​

Endpoint​

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

Απόκριση​

Εκτέλεση εμπλουτισμού καταλόγου​

Endpoint​

Σώμα αιτήματος​

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

Απόκριση​

Λήψη ενός job εμπλουτισμού​

Endpoint​

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

Απόκριση​

Λίστα jobs εμπλουτισμού​

Endpoint​

Παράμετροι query​

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

Απόκριση​

Αποκρίσεις σφαλμάτων​

Επόμενα βήματα​

Τιμολόγηση εκτελέσεων​

Endpoint​

Απόκριση​

Έλεγχος ταυτότητας

Scopes ανά endpoint

Βασικές έννοιες

Λειτουργία μοντέλου και πάροχος

Σχήμα εξόδου

Επιλογείς context

Αποτελέσματα εκτελέσεων

Δημιουργία agent

Endpoint

Σώμα αιτήματος

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

Απόκριση

Λίστα agents

Endpoint

Παράμετροι query

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

Απόκριση

Λήψη ενός agent

Endpoint

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

Ενημέρωση agent

Endpoint

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

Αρχειοθέτηση agent

Endpoint

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

Διαγραφή agent

Endpoint

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

Απόκριση

Δοκιμή (προεπισκόπηση) agent

Endpoint

Σώμα αιτήματος

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

Απόκριση

Λίστα εκτελέσεων agent

Endpoint

Παράμετροι query

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

Απόκριση

Λίστα κλειδιών παρόχων BYO

Endpoint

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

Απόκριση

Upsert κλειδιού παρόχου BYO

Endpoint

Σώμα αιτήματος

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

Απόκριση

Δρομολόγηση του βοηθού και της δημιουργίας περιεχομένου μέσω κλειδιού

Endpoint

Σώμα αιτήματος

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

Απόκριση

Διαγραφή κλειδιού παρόχου BYO

Endpoint

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

Απόκριση

Εκτέλεση εμπλουτισμού καταλόγου

Endpoint

Σώμα αιτήματος

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

Απόκριση

Λήψη ενός job εμπλουτισμού

Endpoint

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

Απόκριση

Λίστα jobs εμπλουτισμού

Endpoint

Παράμετροι query

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

Απόκριση

Αποκρίσεις σφαλμάτων

Επόμενα βήματα

Τιμολόγηση εκτελέσεων

Endpoint

Απόκριση