Documentație API

Aurora Agents API

Tot ce au nevoie dezvoltatorii tăi ca să conecteze agenții AI Aurora la CRM, ERP sau TMS: autentificare, sarcini, conversații, instrumente, webhookuri, limite de tokeni și facturare.

Start rapid Referința agenților

Introducere

API-ul Aurora permite CRM-ului, ERP-ului, TMS-ului sau oricărui backend să predea muncă agenților AI Aurora și să primească rezultate structurate. Fiecare agent are un set fix de tipuri de sarcini cu intrări documentate și ieșiri JSON, așa că sistemul tău se poate baza pe forma a ceea ce primește înapoi.

BASEhttps://api.auroraaisystems.com/v1

Format: JSON prin HTTPS, UTF-8. Trimite Content-Type: application/json cu fiecare corp de cerere.
Ore: ISO 8601 în UTC, de ex. 2026-10-09T08:14:03Z. Lunile de facturare încep la 00:00 UTC pe 1.
ID-uri: prefixate după tipul obiectului — task_, thr_, msg_, tool_, doc_, whk_, evt_, inv_. Agenții folosesc id-uri lizibile precum carla.
Bani: sume zecimale în EUR, de ex. 699.00.
ID-uri de cerere: fiecare răspuns are antetul Aurora-Request-Id. Menționează-l când contactezi suportul.

Agenții

ID agent	Agent	Tipuri principale de sarcini
carla	Carla — Coordonatoare cereri de transport	`transport_request.extract`, `transport_request.qualify`
rio	Rio — Coordonator dispecerat și transportatori	`carrier.match`, `carrier.request_offers`
quinn	Quinn — Specialistă oferte și prețuri	`quote.create`, `quote.compare_offers`
victor	Victor — Specialist dezvoltare vânzări	`lead.qualify`, `lead.research`
mara	Mara — Manager de marketing	`content.plan`, `content.draft`
sofia	Sofia — Coordonatoare suport clienți	`ticket.triage`, `ticket.reply`
ada	Ada — Asistentă contabilitate	`invoice.extract`, `invoice.match`
paul	Paul — Specialist achiziții	`rfq.create`, `offers.compare`
hugo	Hugo — Partener HR și recrutare	`job_ad.draft`, `applications.organize`
lex	Lex — Asistent juridic și conformitate	`contract.review`, `contract.draft`
iris	Iris — Analistă date și raportare	`data.ask`, `report.generate`
atlas	Atlas — Șef de cabinet	`task.route`, `brief.generate`

Contul, agenții și integrările tale sunt configurate împreună cu tine la onboarding. Cheile de test se emit după întâlnirea de start, iar cele de producție la intrarea în producție. Până atunci, tot ce e pe această pagină poate fi încercat în sandbox.

Start rapid

Patru pași de la un email din inbox la o înregistrare structurată în CRM-ul tău.

1. Păstrează cheia de test

Ține cheile pe serverul tău, ca variabilă de mediu. Nu le pune niciodată într-un browser, într-o aplicație mobilă sau într-un repository public.

Terminal

export AURORA_API_KEY="aur_test_…"

2. Creează o sarcină

Cere-i Carlei să transforme un email de client într-o cerere de transport. Câmpul metadata se întoarce neschimbat, ca să poți potrivi rezultatul cu înregistrarea din CRM.

curl https://api.auroraaisystems.com/v1/agents/carla/tasks \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transport_request.extract",
    "input": {
      "channel": "email",
      "from": "mihai@agrodelta.example",
      "subject": "Truck Pitesti - Lyon",
      "body": "Hi, we need a truck from Pitești to Lyon next week, 14 europallets ~9t, not stackable. Can you send a price?"
    },
    "metadata": {
      "crm_record_id": "REQ-2041"
    }
  }'

202 Accepted

{
  "id": "task_01J9Z3K8R4",
  "object": "task",
  "agent_id": "carla",
  "type": "transport_request.extract",
  "status": "queued",
  "metadata": {
    "crm_record_id": "REQ-2041"
  },
  "created_at": "2026-10-09T08:14:03Z"
}

3. Obține rezultatul

Înregistrează un webhook și primește task.completed sau interoghează sarcina până când statusul ei e final.

curl https://api.auroraaisystems.com/v1/tasks/task_01J9Z3K8R4 \
  -H "Authorization: Bearer $AURORA_API_KEY"

200 OK

{
  "id": "task_01J9Z3K8R4",
  "object": "task",
  "agent_id": "carla",
  "type": "transport_request.extract",
  "status": "completed",
  "output": {
    "transport_request": {
      "pickup": {
        "city": "Pitești",
        "country": "RO",
        "postcode": null,
        "date": null
      },
      "delivery": {
        "city": "Lyon",
        "country": "FR",
        "postcode": null
      },
      "cargo": {
        "pallet_type": "EUR",
        "pallets": 14,
        "stackable": false,
        "weight_kg": 9000,
        "loading_meters": 5.6,
        "adr": false
      },
      "missing_fields": [
        "pickup.date",
        "delivery.postcode"
      ],
      "language": "en",
      "confidence": 0.93
    }
  },
  "handoffs": [
    {
      "agent_id": "quinn",
      "task_id": "task_01J9Z3M2QP",
      "type": "quote.create",
      "mode": "auto"
    }
  ],
  "parent_task_id": null,
  "escalation": null,
  "error": null,
  "usage": {
    "input_tokens": 3120,
    "output_tokens": 640,
    "total_tokens": 3760
  },
  "metadata": {
    "crm_record_id": "REQ-2041"
  },
  "created_at": "2026-10-09T08:14:03Z",
  "completed_at": "2026-10-09T08:14:09Z"
}

4. Folosește-l

Scrie output.transport_request în înregistrarea din CRM. Carla i-a predat automat cererea și lui Quinn — oferta ei vine ca un alt eveniment task.completed după ce clientul trimite detaliile lipsă.

Autentificare

Autentifică fiecare cerere cu o cheie secretă în antetul Authorization.

Antet HTTP

Authorization: Bearer aur_live_4f9c…

Prefixul cheii	Mediu	Comportament
`aur_test_`	Sandbox	Aceiași agenți și același API. 500.000 de tokeni gratuiți pe lună. Apelurile de instrumente și webhookurile merg către endpointurile tale de test. Nu se facturează niciodată.
`aur_live_`	Producție	Muncă reală, măsurată și facturată. Emisă la intrarea în producție.

Permisiuni și restricții

Fiecare cheie poate fi limitată la anumite permisiuni și agenți și poate avea propria limită lunară de tokeni. Permisiuni disponibile: agents:read, agents:write, tasks:read, tasks:write, threads:write, tools:write, knowledge:write, webhooks:write, usage:read, limits:write, billing:read.

Creează, restricționează și rotește cheile în consolă. O cheie revocată nu mai funcționează imediat.
Pentru un widget de chat pe site, apelează Aurora din backendul tău — niciodată din browserul vizitatorului.
O cheie lipsă sau invalidă returnează 401 authentication_error; o cheie fără permisiunea potrivită returnează 403 permission_denied.

Concepte de bază

Obiect	Ce este
Agent	Un lucrător AI configurat, cu o singură sarcină. Manifestul lui combină persona, abilitățile, instrumentele, cunoștințele, protecțiile și limitele.
Sarcină	O unitate de muncă pentru un agent: un tip, o intrare și, la final, o ieșire JSON. Sarcinile rulează asincron.
Fir de discuție și mesaj	O conversație — un chat de suport, un schimb pe WhatsApp. Firul păstrează istoricul; fiecare mesaj primește răspunsul agentului.
Instrument	O acțiune din sistemele tale pe care un agent o poate apela, cum ar fi găsirea unui client sau crearea unei comenzi.
Document de cunoștințe	Un fișier sau un text pe care agentul se poate baza: tarife, termeni, politici, șabloane.
Predare	Transmiterea unui rezultat finalizat către următorul agent, automat sau după confirmarea ta.
Consum și limite	Tokeni măsurați la fiecare apel de model; ei declanșează alertele, limitele și linia de tokeni suplimentari de pe factură.
Eveniment	O notificare webhook că s-a întâmplat ceva — o sarcină s-a finalizat, s-a atins o limită, o factură a fost plătită.

Agenți

Obiectul agent este manifestul agentului: cum sună, ce poate face, ce are voie să atingă și unde se oprește. Le citești pe toate; poți schimba persona, statusul și limitele.

Obiectul agent

Obiect agent

{
  "id": "carla",
  "object": "agent",
  "name": "Carla",
  "title": "Transport Request Coordinator",
  "status": "active",
  "persona": {
    "traits": [
      "meticulous",
      "calm under volume",
      "politely persistent"
    ],
    "tone": {
      "formality": 3,
      "description": "Warm and precise"
    },
    "languages": [
      "en",
      "ro",
      "de"
    ],
    "reply_in_sender_language": true,
    "signature": "Carla, dispatch desk"
  },
  "skills": [
    "transport_request.extract",
    "transport_request.qualify",
    "transport_request.follow_up"
  ],
  "tools": [
    "crm.find_customer",
    "crm.create_request"
  ],
  "knowledge": [
    "kb_lanes",
    "kb_general_terms"
  ],
  "guardrails": {
    "never": [
      "quote_prices",
      "invent_missing_data"
    ],
    "handover_when": [
      "adr_goods",
      "oversized_cargo",
      "estimated_value_eur > 20000"
    ]
  },
  "handoffs": [
    {
      "on": "transport_request.qualified",
      "to": "quinn",
      "task_type": "quote.create",
      "mode": "auto"
    }
  ],
  "limits": {
    "monthly_token_limit": null,
    "max_output_tokens": 4000
  },
  "created_at": "2026-10-01T09:00:00Z",
  "updated_at": "2026-10-06T15:20:11Z"
}

Parametru	Descriere
id string	Id lizibil al agentului, de ex. `carla`. Nu se schimbă niciodată, chiar dacă redenumești agentul.
status enum	`active`, `paused` sau `configuring`. Agenții puși pe pauză resping sarcinile noi cu `409`.
persona object	Numele afișat, trăsăturile, tonul (formalitate 1–5), limbile, dacă răspunde în limba expeditorului și semnătura.
skills array	Tipurile de sarcini pe care le rulează acest agent. Vezi referința agenților.
tools array	Numele instrumentelor pe care acest agent le poate apela.
knowledge array	Colecțiile de cunoștințe pe care agentul le poate folosi.
guardrails object	Ce nu face niciodată agentul și când predă unui om. Doar citire.
handoffs array	Ce rezultat merge la ce agent și cum. Doar citire.
limits object	Limita lunară de tokeni pentru acest agent (sau `null` pentru fondul comun) și numărul maxim de tokeni de ieșire per apel de model.

Listează agenții

GET/v1/agents

curl https://api.auroraaisystems.com/v1/agents \
  -H "Authorization: Bearer $AURORA_API_KEY"

Obține un agent

GET/v1/agents/{agent_id}

Actualizează un agent

PATCH/v1/agents/{agent_id}

Doar câmpurile de mai jos pot fi schimbate prin API. Abilitățile, instrumentele, protecțiile și predările se schimbă împreună cu echipa noastră, ca fiecare modificare să fie testată în sandbox înainte să ajungă la clienții tăi.

Parametru	Descriere
persona.display_name string	Numele pe care îl văd clienții, de ex. dacă o redenumești pe Carla ca să se potrivească brandului tău.
persona.tone.formality integer 1–5	1 e foarte formal, 5 e foarte relaxat.
persona.languages array	Coduri ISO 639-1 ale limbilor în care scrie agentul, de ex. `["en","ro","de"]`.
persona.reply_in_sender_language boolean	Răspunde în limba mesajului primit, dacă aceasta e în listă.
persona.signature string	Formula de încheiere folosită în mesajele trimise, până la 60 de caractere.
status enum	`active` sau `paused`.
limits.monthly_token_limit integer sau null	Plafonul lunar pentru acest agent în cadrul fondului tău comun.
limits.max_output_tokens integer	Până la 4.000, dacă nu s-a convenit altfel.

curl -X PATCH https://api.auroraaisystems.com/v1/agents/carla \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": {
      "tone": {
        "formality": 2
      },
      "signature": "Carla, dispatch desk — Northline Logistics"
    }
  }'

Sarcini

O sarcină e o unitate de muncă pentru un agent. Sarcinile rulează asincron: creezi una, apoi primești rezultatul prin webhook sau prin interogare.

Creează o sarcină

POST/v1/agents/{agent_id}/tasks

Parametru	Descriere
type string obligatoriu	Un tip de sarcină pe care agentul îl suportă, de ex. `transport_request.extract`.
input object obligatoriu	Intrarea pentru tipul de sarcină. Câmpurile pentru fiecare tip sunt listate în referința agenților; o intrare invalidă returnează `422`.
metadata object	Până la 20 de perechi cheie–valoare returnate neschimbate, de ex. id-ul înregistrării din CRM.
callback_url string	Trimite evenimentele acestei sarcini la acest URL în loc de webhookurile înregistrate.
thread_id string	Atașează sarcina la o conversație, ca agentul să-i vadă istoricul.
priority enum	`normal` (implicit) sau `high`.
handoff enum	`auto`, `suggest` sau `none`. Implicit, cel din manifestul agentului.
max_output_tokens integer	Reduce limita de ieșire pentru această sarcină.

Trimite un antet Idempotency-Key ca o cerere reîncercată să nu creeze niciodată o sarcină duplicat. Răspunsul este 202 Accepted, cu sarcina în statusul queued.

Obiectul sarcină

Obiect sarcină

{
  "id": "task_01J9Z3K8R4",
  "object": "task",
  "agent_id": "carla",
  "type": "transport_request.extract",
  "status": "completed",
  "output": {
    "transport_request": {
      "pickup": {
        "city": "Pitești",
        "country": "RO",
        "postcode": null,
        "date": null
      },
      "delivery": {
        "city": "Lyon",
        "country": "FR",
        "postcode": null
      },
      "cargo": {
        "pallet_type": "EUR",
        "pallets": 14,
        "stackable": false,
        "weight_kg": 9000,
        "loading_meters": 5.6,
        "adr": false
      },
      "missing_fields": [
        "pickup.date",
        "delivery.postcode"
      ],
      "language": "en",
      "confidence": 0.93
    }
  },
  "handoffs": [
    {
      "agent_id": "quinn",
      "task_id": "task_01J9Z3M2QP",
      "type": "quote.create",
      "mode": "auto"
    }
  ],
  "parent_task_id": null,
  "escalation": null,
  "error": null,
  "usage": {
    "input_tokens": 3120,
    "output_tokens": 640,
    "total_tokens": 3760
  },
  "metadata": {
    "crm_record_id": "REQ-2041"
  },
  "created_at": "2026-10-09T08:14:03Z",
  "completed_at": "2026-10-09T08:14:09Z"
}

Statusurile sarcinilor

Status	Semnificație
`queued`	Acceptată și în așteptarea rulării.
`running`	Agentul lucrează la ea.
`requires_action`	Agentul a apelat un instrument în modul client și așteaptă rezultatul tău. Vezi trimiterea rezultatelor instrumentelor.
`completed`	Finalizată; `output` conține rezultatul.
`escalated`	O protecție a predat munca unui om. `escalation` conține motivul și un rezumat pentru echipa ta.
`failed`	Nu s-a putut finaliza; `error` explică de ce. Eșecurile cauzate de noi nu se facturează.
`cancelled`	Anulată de tine. Tokenii deja folosiți se facturează.

Obține o sarcină

GET/v1/tasks/{task_id}

Listează sarcinile

GET/v1/tasks

Parametru	Descriere
agent_id string	Doar sarcinile acestui agent.
status enum	Doar sarcinile în acest status.
type string	Doar acest tip de sarcină.
created_after / created_before timestamp	Interval de timp.
limit / cursor integer / string	Vezi paginarea.

Trimite rezultatele instrumentelor

POST/v1/tasks/{task_id}/tool_outputs

Când un agent apelează un instrument înregistrat în modul client, sarcina se oprește în requires_action și primești task.requires_action:

Sarcină care așteaptă rezultatul instrumentului tău

{
  "id": "task_01J9Z3K8R4",
  "object": "task",
  "agent_id": "carla",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "tool_calls": [
      {
        "id": "call_7Hk2",
        "tool": "crm.find_customer",
        "arguments": {
          "email": "mihai@agrodelta.example"
        }
      }
    ]
  }
}

curl https://api.auroraaisystems.com/v1/tasks/task_01J9Z3K8R4/tool_outputs \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_7Hk2",
        "output": {
          "customer_id": "C-1042",
          "name": "Agro Delta SRL",
          "payment_terms_days": 30
        }
      }
    ]
  }'

Anulează o sarcină

POST/v1/tasks/{task_id}/cancel

Sarcinile în queued, running sau requires_action pot fi anulate. Tokenii deja folosiți se facturează.

Mesaje și fire de discuție

Folosește firele de discuție pentru conversații — un chat de suport, un schimb pe WhatsApp, un asistent intern. Firul păstrează istoricul; fiecare mesaj trimis returnează răspunsul agentului.

Creează un fir de discuție

POST/v1/threads

Parametru	Descriere
agent_id string obligatoriu	Agentul căruia îi aparține conversația, de ex. `sofia`.
channel enum	`chat`, `email`, `whatsapp` sau `internal`. Influențează formatarea și lungimea.
contact object	Numele, emailul și telefonul persoanei care scrie. Folosite pentru a căuta datele pe care agentul i le poate comunica.
metadata object	Returnat neschimbat.

curl https://api.auroraaisystems.com/v1/threads \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sofia",
    "channel": "whatsapp",
    "contact": {
      "name": "Mihai Popa",
      "phone": "+40700000000"
    },
    "metadata": {
      "crm_contact_id": "C-1042-01"
    }
  }'

Trimite un mesaj

POST/v1/threads/{thread_id}/messages

curl https://api.auroraaisystems.com/v1/threads/thr_01J9ZC6Y2B/messages \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "Hello, where is our shipment to Lyon?",
    "stream": false
  }'

Răspunsul agentului

{
  "id": "msg_01J9ZC7T1D",
  "object": "message",
  "thread_id": "thr_01J9ZC6Y2B",
  "role": "agent",
  "agent_id": "sofia",
  "content": "Hi Mihai! Your shipment SHP-5530 left Pitești on 14 October and is now near Dijon. The driver’s ETA in Lyon is today at 16:30.",
  "handover": false,
  "sources": [
    "tms:shipment:SHP-5530"
  ],
  "usage": {
    "input_tokens": 2210,
    "output_tokens": 96,
    "total_tokens": 2306
  },
  "created_at": "2026-10-16T13:02:44Z"
}

Dacă handover este true, agentul s-a oprit și trebuie să continue un om; conținutul mesajului îi spune asta clientului, iar task.escalated conține rezumatul pentru echipa ta.

Streaming

Setează "stream": true ca să primești răspunsul ca server-sent events (text/event-stream) în timp ce e scris. Evenimente: message.delta, message.completed și error.

Flux de evenimente

event: message.delta
data: {"delta":"Hi Mihai! Your shipment SHP-5530 "}

event: message.delta
data: {"delta":"left Pitești on 14 October and is now near Dijon…"}

event: message.completed
data: {"id":"msg_01J9ZC7T1D","handover":false,"usage":{"input_tokens":2210,"output_tokens":96,"total_tokens":2306}}

Listează mesajele și șterge un fir de discuție

GET/v1/threads/{thread_id}/messages

DELETE/v1/threads/{thread_id}

Ștergerea unui fir îl elimină definitiv, cu toate mesajele lui.

Instrumente

Instrumentele le permit agenților să acționeze în sistemele tale. Descrii o acțiune cu o JSON Schema; agentul decide când s-o apeleze și cu ce argumente. Nimic nu rulează în sistemele tale dacă nu înregistrezi un instrument pentru asta.

Înregistrează un instrument

POST/v1/tools

Parametru	Descriere
name string obligatoriu	Nume unic, de ex. `crm.find_customer`. Litere, cifre, puncte și underscore.
description string obligatoriu	Ce face instrumentul și când trebuie folosit. Agenții citesc asta, așa că fii specific.
input_schema object obligatoriu	JSON Schema pentru argumente.
mode enum obligatoriu	`webhook`: noi apelăm URL-ul tău. `client`: sarcina se oprește și rulezi tu instrumentul.
url string	Obligatoriu în modul webhook. Doar HTTPS.
agents array obligatoriu	Id-urile agenților care au voie să apeleze instrumentul.
timeout_ms integer	Cât așteptăm răspunsul tău în modul webhook. Implicit 10.000, maximum 30.000.

curl https://api.auroraaisystems.com/v1/tools \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm.find_customer",
    "description": "Find a customer in our CRM by email address or VAT number.",
    "mode": "webhook",
    "url": "https://crm.yourcompany.example/aurora/tools",
    "agents": [
      "carla",
      "sofia",
      "ada"
    ],
    "timeout_ms": 10000,
    "input_schema": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email"
        },
        "vat_id": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  }'

Modul webhook

Trimitem un POST semnat la URL-ul tău — aceeași schemă de semnătură ca la webhookuri — și așteptăm răspunsul tău JSON.

Noi trimitem

{
  "tool": "crm.find_customer",
  "tool_call_id": "call_7Hk2",
  "task_id": "task_01J9Z3K8R4",
  "agent_id": "carla",
  "arguments": {
    "email": "mihai@agrodelta.example"
  }
}

Tu răspunzi (200 OK)

{
  "output": {
    "customer_id": "C-1042",
    "name": "Agro Delta SRL",
    "payment_terms_days": 30
  }
}

Dacă endpointul tău returnează o eroare sau depășește timpul, agentul află că instrumentul a eșuat. Reîncearcă o dată, continuă fără rezultat dacă poate face asta în siguranță sau escaladează sarcina.

Modul client

Sarcina se oprește cu statusul requires_action. Execuți acțiunea tu și trimiți rezultatul prin trimiterea rezultatelor instrumentelor. Folosește modul client când sistemul tău nu poate primi apeluri din exterior.

Listează și șterge instrumente

GET/v1/tools

DELETE/v1/tools/{tool_id}

Cunoștințe

Încarcă documentele pe care trebuie să se bazeze agenții — liste de prețuri, termeni, politici, șabloane, cazuri anterioare. Când un agent lucrează la o sarcină, extrage pasajele relevante și folosește faptele tale în loc de cunoștințe generale.

Încarcă un document

POST/v1/knowledge/documents

Parametru	Descriere
file file	PDF, DOCX, XLSX, CSV, TXT, MD sau HTML, până la 50 MB. Trimite ca `multipart/form-data`.
url / text string	În locul unui fișier, un URL public de descărcat sau text simplu, ca JSON.
title string obligatoriu	Afișat în consolă și în sursele agentului.
agents array obligatoriu	Id-urile agenților care pot folosi documentul.
collection string	Grupează documentele, de ex. `kb_lanes`.

cURL — încărcare multipart

curl https://api.auroraaisystems.com/v1/knowledge/documents \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -F file=@road-tariffs-2026.xlsx \
  -F title="Road tariffs 2026" \
  -F "agents[]=quinn" \
  -F "agents[]=carla"

201 Created

{
  "id": "doc_8KQ2M1",
  "object": "knowledge_document",
  "title": "Road tariffs 2026",
  "status": "processing",
  "agents": [
    "quinn",
    "carla"
  ],
  "bytes": 184320,
  "created_at": "2026-10-06T10:41:00Z"
}

Statusul trece de la processing la ready sau failed și primești knowledge.document.ready sau knowledge.document.failed. Încărcarea și indexarea sunt gratuite; pasajele folosite într-o sarcină se socotesc tokeni de intrare.

Listează, obține și șterge

GET/v1/knowledge/documents

GET/v1/knowledge/documents/{document_id}

DELETE/v1/knowledge/documents/{document_id}

Ștergerea unui document elimină fișierul și indexul lui; agenții nu-l mai folosesc.

Predări

Agenții își predau munca unul altuia așa cum o face echipa ta: Carla completează o cerere de transport, Quinn îi calculează prețul, Rio rezervă transportatorul. Predările sunt definite în manifestul fiecărui agent și stabilite cu tine la configurare.

Mod	Ce se întâmplă
`auto`	Următoarea sarcină se creează automat, cu ieșirea finalizată ca intrare.
`suggest`	Ieșirea include `suggested_handoffs`; nu se întâmplă nimic până nu confirmi.
`none`	Fără predare; sistemul tău decide ce urmează.

Confirmă o predare sugerată

POST/v1/tasks/{task_id}/handoff

curl https://api.auroraaisystems.com/v1/tasks/task_01J9Z3K8R4/handoff \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "quinn",
    "type": "quote.create",
    "input_overrides": {
      "pricing_rules": "key_accounts"
    }
  }'

Fiecare predare e înregistrată în tabloul handoffs al sarcinii părinte și în parent_task_id al sarcinii copil și declanșează handoff.created. Atlas poate coordona lanțuri mai lungi pentru tine.

Webhookuri

Webhookurile trimit evenimentele către sistemul tău pe măsură ce se întâmplă, ca să nu fie nevoie să interoghezi.

Înregistrează un endpoint

POST/v1/webhooks

curl https://api.auroraaisystems.com/v1/webhooks \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://crm.yourcompany.example/hooks/aurora",
    "events": [
      "task.completed",
      "task.escalated",
      "limit.reached",
      "invoice.created"
    ],
    "description": "CRM production"
  }'

201 Created — secretul e afișat o singură dată

{
  "id": "whk_3MZ81Q",
  "object": "webhook",
  "url": "https://crm.yourcompany.example/hooks/aurora",
  "events": [
    "task.completed",
    "task.escalated",
    "limit.reached",
    "invoice.created"
  ],
  "secret": "whsec_…",
  "created_at": "2026-10-06T10:02:00Z"
}

Evenimente

Eveniment	Trimis când
`task.completed`	O sarcină s-a încheiat cu o ieșire.
`task.failed`	O sarcină nu s-a putut finaliza.
`task.requires_action`	O sarcină așteaptă rezultatul instrumentului tău.
`task.escalated`	O protecție a predat o sarcină unui om.
`handoff.created`	Un agent a predat munca altui agent.
`message.completed`	Un agent a terminat un răspuns într-un fir de discuție.
`knowledge.document.ready`	Un document e indexat și în uz.
`knowledge.document.failed`	Un document nu a putut fi procesat.
`usage.threshold_reached`	Consumul a depășit unul dintre pragurile tale de alertă.
`limit.reached`	S-a atins o limită de tokeni sau un plafon de cheltuieli.
`invoice.created`	S-a emis o factură nouă.
`invoice.paid`	O factură a fost plătită.
`invoice.payment_failed`	O plată automată a eșuat.
`agent.updated`	S-au schimbat persona, statusul sau limitele unui agent.

Payload

Plicul evenimentului

{
  "id": "evt_01J9Z4D2WQ",
  "object": "event",
  "type": "task.completed",
  "created_at": "2026-10-09T08:14:09Z",
  "data": {
    "object": {
      "id": "task_01J9Z3K8R4",
      "object": "task",
      "agent_id": "carla",
      "status": "completed",
      "output": {
        "transport_request": {
          "…": "…"
        }
      },
      "metadata": {
        "crm_record_id": "REQ-2041"
      }
    }
  }
}

Verificarea semnăturilor

Fiecare webhook și fiecare apel de instrument în modul webhook are antetul Aurora-Signature, de ex. t=1760000043,v1=6c1f…. Calculează un HMAC-SHA256 cu secretul endpointului peste {t}.{raw body}, compară-l în timp constant cu v1 și respinge cererile mai vechi de 5 minute.

import crypto from "node:crypto";

// rawBody: the request body exactly as received, before JSON parsing
export function verifyAuroraSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1 || "", "hex");
  const exp = Buffer.from(expected, "hex");
  return given.length === exp.length && crypto.timingSafeEqual(given, exp);
}

Livrare și reîncercări

Răspunde cu un status 2xx în 10 secunde, apoi fă munca grea în fundal. Altfel reîncercăm cu backoff exponențial până la 24 de ore. Evenimentele pot sosi de mai multe ori sau în altă ordine — salvează id-ul evenimentului și ignoră duplicatele.

Consum și limite de tokeni

Fiecare apel de model făcut pentru sarcinile tale e măsurat în tokeni. Consumul declanșează alertele, limitele și linia de tokeni suplimentari de pe factură.

Cum se numără tokenii

Tokeni de intrare: instrucțiunile și persona agentului, intrarea sarcinii, istoricul conversației, pasajele de cunoștințe extrase și rezultatele instrumentelor.
Tokeni de ieșire: tot ce scrie agentul, inclusiv argumentele apelurilor de instrumente.
Consumul unei sarcini e suma tuturor apelurilor ei de model. Tokenii de intrare și de ieșire au același preț.
Fiecare agent include 10.000.000 de tokeni pe lună, puși în comun pentru toți agenții tăi și resetați la 00:00 UTC pe 1. Tokenii suplimentari costă 15 € per milion, măsurați la fiecare 1.000.
Încărcarea și indexarea cunoștințelor sunt gratuite. Sarcinile care eșuează din cauza unei erori de partea noastră nu se facturează.

Fiecare sarcină și fiecare mesaj returnează un obiect usage, iar fiecare răspuns are aceste antete:

Antet	Valoare
`Aurora-Tokens-Used`	Tokenii folosiți de această cerere.
`Aurora-Tokens-Remaining`	Tokenii incluși rămași în luna de facturare curentă, la nivelul întregului cont.
`Aurora-Spend-Remaining`	EUR rămași până la plafonul de cheltuieli, când politica este `cap`.

Obține consumul

GET/v1/usage

Parametru	Descriere
period YYYY-MM	Luna de facturare. Implicit, cea curentă.
group_by enum	`agent` (implicit), `api_key` sau `day`.

curl https://api.auroraaisystems.com/v1/usage?period=2026-10&group_by=agent \
  -H "Authorization: Bearer $AURORA_API_KEY"

200 OK

{
  "object": "usage",
  "period": "2026-10",
  "included_tokens": 30000000,
  "used_tokens": 18412360,
  "remaining_included_tokens": 11587640,
  "overage_tokens": 0,
  "overage_amount_eur": 0.00,
  "by_agent": [
    {
      "agent_id": "carla",
      "input_tokens": 6904112,
      "output_tokens": 1301228,
      "total_tokens": 8205340,
      "tasks": 1874
    },
    {
      "agent_id": "quinn",
      "input_tokens": 5140215,
      "output_tokens": 964665,
      "total_tokens": 6104880,
      "tasks": 932
    },
    {
      "agent_id": "rio",
      "input_tokens": 3512018,
      "output_tokens": 590122,
      "total_tokens": 4102140,
      "tasks": 611
    }
  ],
  "updated_at": "2026-10-19T08:00:00Z"
}

Limite

Limitele decid ce se întâmplă când tokenii incluși se termină și împiedică un singur agent sau o singură integrare să folosească tot fondul comun. Stabilești politica la comandă și o poți schimba oricând; modificările intră în vigoare imediat.

Obiectul limite

GET/v1/limits

Obiect limite

{
  "object": "limits",
  "overage_policy": "cap",
  "monthly_spend_cap_eur": 500.00,
  "alert_thresholds_pct": [
    50,
    80,
    100
  ],
  "alert_emails": [
    "finance@yourcompany.example"
  ],
  "agents": {
    "carla": {
      "monthly_token_limit": 12000000
    },
    "quinn": {
      "monthly_token_limit": null
    }
  },
  "api_keys": {
    "key_crm_prod": {
      "monthly_token_limit": null
    }
  },
  "rate_limits": {
    "requests_per_minute_per_agent": 60,
    "tokens_per_minute_per_agent": 200000
  },
  "max_output_tokens": 4000
}

Actualizează limitele

PATCH/v1/limits

Parametru	Descriere
overage_policy enum	`hard_stop`: oprire la tokenii incluși. `cap`: permite tokeni suplimentari până la `monthly_spend_cap_eur`. `unlimited`: permite tokeni suplimentari fără plafon.
monthly_spend_cap_eur number	Cheltuiala maximă pe tokeni suplimentari pe lună, fără TVA. Folosit cu `cap`.
alert_thresholds_pct array	Procentele din tokenii incluși care declanșează `usage.threshold_reached`.
alert_emails array	Cine primește emailurile de alertă.
agents.{agent_id}.monthly_token_limit integer sau null	Limita lunară pentru un agent.
api_keys.{key_id}.monthly_token_limit integer sau null	Limita lunară pentru o cheie API.

curl -X PATCH https://api.auroraaisystems.com/v1/limits \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "overage_policy": "cap",
    "monthly_spend_cap_eur": 800,
    "agents": {
      "quinn": {
        "monthly_token_limit": 8000000
      }
    }
  }'

Limitele de rată sunt doar pentru citire; contactează-ne ca să le mărim.

Când se atinge o limită

Situație	Răspuns
Tokenii incluși s-au terminat și politica este `hard_stop`	`402` cu codul `quota_exceeded`
Plafon de cheltuieli atins (politica `cap`)	`402` cu codul `spend_cap_reached`
Limita lunară a unui agent atinsă	`402` cu codul `agent_limit_reached`, doar pentru acel agent
Limita lunară a unei chei API atinsă	`402` cu codul `key_limit_reached`, doar pentru acea cheie

Sarcinile deja în desfășurare se termină normal. Sarcinile și mesajele noi sunt respinse până în luna de facturare următoare sau până crești limita. Un eveniment limit.reached se trimite o singură dată per limită pe lună.

402 Payment Required

{
  "error": {
    "type": "limit_error",
    "code": "spend_cap_reached",
    "message": "Monthly spend cap of €500.00 reached. Raise monthly_spend_cap_eur or wait until 1 November 2026.",
    "request_id": "req_01J9ZB4N7F"
  }
}

Facturare și facturi

Citește abonamentul, previzualizează factura următoare și descarcă facturile — de exemplu, ca să le înregistrezi automat în ERP.

Taxa de configurare se facturează la comandă.
Abonamentele încep la intrarea în producție; prima lună se calculează proporțional, la zi.
Pe 1 ale fiecărei luni se emite o singură factură: abonamentele pentru luna nouă în avans, tokenii suplimentari din luna anterioară la final și, pentru plățile cu cardul, comisionul procesatorului refacturat la cost, acolo unde legea permite.
Cardul și debitul direct SEPA se încasează automat la data facturii; transferurile bancare au termen de 14 zile.
Pentru companiile din România, facturile sunt transmise și prin e-Factura.

Abonament

GET/v1/billing/subscription

Obiect abonament

{
  "object": "subscription",
  "status": "active",
  "currency": "EUR",
  "agents": [
    {
      "agent_id": "carla",
      "status": "active",
      "unit_price": 699.00,
      "active_since": "2026-10-06"
    },
    {
      "agent_id": "quinn",
      "status": "active",
      "unit_price": 699.00,
      "active_since": "2026-10-06"
    },
    {
      "agent_id": "rio",
      "status": "active",
      "unit_price": 699.00,
      "active_since": "2026-10-06"
    }
  ],
  "current_period": {
    "start": "2026-10-01",
    "end": "2026-10-31"
  },
  "overage_price_per_million": 15.00,
  "payment_method": {
    "type": "sepa_debit",
    "last4": "3000"
  }
}

Adaugă sau elimină agenți

POST/v1/billing/subscription/agents

curl https://api.auroraaisystems.com/v1/billing/subscription/agents \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sofia"
  }'

Agentul e adăugat în statusul configuring și devine activ după ce e configurat pentru tine; facturarea începe la activare, proporțional. Dacă are nevoie de o integrare nouă, confirmăm mai întâi scopul cu tine.

DELETE/v1/billing/subscription/agents/{agent_id}

Elimină agentul la sfârșitul lunii de facturare curente.

Factura următoare

GET/v1/billing/upcoming

Previzualizare factură

{
  "object": "invoice_preview",
  "issue_date": "2026-11-01",
  "currency": "EUR",
  "lines": [
    {
      "description": "Agent subscription — November 2026",
      "quantity": 3,
      "unit_price": 699.00,
      "amount": 2097.00
    },
    {
      "description": "Extra tokens — October 2026",
      "quantity": 0,
      "unit": "1M tokens",
      "unit_price": 15.00,
      "amount": 0.00
    }
  ],
  "subtotal": 2097.00,
  "vat": {
    "treatment": "domestic",
    "rate": 21,
    "amount": 440.37
  },
  "total": 2537.37
}

Facturi

GET/v1/billing/invoices

GET/v1/billing/invoices/{invoice_id}

GET/v1/billing/invoices/{invoice_id}/pdf

Obiect factură

{
  "id": "inv_2026_11_0042",
  "object": "invoice",
  "number": "AUR 0142",
  "status": "paid",
  "issue_date": "2026-11-01",
  "due_date": "2026-11-01",
  "currency": "EUR",
  "subtotal": 2097.00,
  "vat_amount": 440.37,
  "total": 2537.37,
  "payment": {
    "method": "sepa_debit",
    "status": "succeeded",
    "paid_at": "2026-11-04T06:12:00Z"
  },
  "e_invoice": {
    "system": "RO e-Factura",
    "status": "accepted"
  },
  "pdf_url": "https://api.auroraaisystems.com/v1/billing/invoices/inv_2026_11_0042/pdf"
}

Parametru	Descriere
number string	Seria și numărul, așa cum sunt emise de sistemul nostru de facturare.
status enum	`open`, `paid`, `overdue` sau `void`.
payment object	Metoda și statusul plății automate, dacă există.
e_invoice object sau null	Pentru companiile din România: `pending`, `sent`, `accepted` sau `rejected` în e-Factura.

Erori

Erorile folosesc coduri de status HTTP standard și un corp JSON consecvent.

422 Unprocessable Entity

{
  "error": {
    "type": "validation_error",
    "code": "missing_field",
    "message": "input.body is required when input.channel is \"email\".",
    "param": "input.body",
    "request_id": "req_01J9ZA2K5C"
  }
}

Status	Tip	Când
400	`invalid_request_error`	JSON malformat, parametru necunoscut sau tip greșit.
401	`authentication_error`	Cheie API lipsă, invalidă sau revocată.
402	`limit_error`	S-a atins o limită de tokeni sau un plafon de cheltuieli. `code` spune care.
403	`permission_denied`	Cheia nu are permisiunea sau accesul la agent pentru această cerere.
404	`not_found`	Obiectul nu există sau nu e vizibil pentru această cheie.
409	`conflict`	Cheie de idempotență refolosită cu un alt corp sau starea obiectului nu permite acțiunea.
413	`payload_too_large`	Corpul cererii sau fișierul depășește limita de mărime.
422	`validation_error`	Intrarea nu corespunde schemei tipului de sarcină; `param` numește câmpul.
429	`rate_limit_error`	Prea multe cereri sau tokeni pe minut.
500	`api_error`	Ceva n-a mers de partea noastră. Poți reîncerca în siguranță cu același Idempotency-Key.
503	`overloaded`	Problemă temporară de capacitate. Reîncearcă cu backoff.

Fiecare eroare include un request_id. Trimite-l la support@auroraaisystems.com dacă ai nevoie de ajutor.

Limite de rată

Implicit, fiecare agent acceptă 60 de cereri și 200.000 de tokeni pe minut în contul tău. Limite mai mari sunt disponibile la cerere.

Antet	Semnificație
`RateLimit-Limit`	Cereri permise în fereastra curentă.
`RateLimit-Remaining`	Cereri rămase în fereastră.
`RateLimit-Reset`	Secunde până la resetarea ferestrei.
`Retry-After`	Trimis cu 429: secunde de așteptat înainte de reîncercare.

Reîncearcă 429 și 503 cu backoff exponențial și jitter. Nu reîncerca alte erori 4xx fără să modifici cererea.

Idempotență

Trimite un antet Idempotency-Key — orice șir unic, de exemplu un UUID — cu cererile POST. Dacă aceeași cheie sosește din nou în 24 de ore cu același corp, primești răspunsul inițial în loc de o sarcină duplicat. Aceeași cheie cu un corp diferit returnează 409 conflict.

Paginare

Endpointurile de listare returnează pagini de până la 100 de obiecte (implicit 20). Trimite limit și, pentru pagina următoare, cursor.

Răspuns de listare

{
  "object": "list",
  "data": [
    {
      "id": "task_01J9Z3K8R4",
      "object": "task",
      "status": "completed"
    }
  ],
  "has_more": true,
  "next_cursor": "c_9f3a1e"
}

Versionare

Fixează o versiune cu antetul Aurora-Version, de ex. Aurora-Version: 2026-10-01. Fără antet se folosește versiunea contului tău, stabilită la intrarea în producție. Modificările incompatibile apar doar în versiuni noi, datate, anunțate în istoricul modificărilor. Câmpuri, tipuri de evenimente și tipuri de sarcini noi pot apărea oricând, așa că ignoră câmpurile pe care nu le recunoști.

Referința agenților

Tipurile de sarcini și exemple de payload pentru fiecare agent. Câmpurile exacte de intrare și schemele de ieșire pentru contul tău — inclusiv câmpurile adăugate pentru sistemele tale la configurare — sunt disponibile în consolă și prin GET /v1/agents/{agent_id}.

Carla — Coordonatoare cereri de transport

ID agent carla, Operațiuni. Pagina agentului

Tip de sarcină	Ce face
`transport_request.extract`	Transformă un email, un mesaj sau un document într-o cerere de transport structurată
`transport_request.qualify`	Verifică dacă cererea e completă și se potrivește rutelor și regulilor tale
`transport_request.follow_up`	Redactează sau trimite mesajul prin care clientul e rugat să completeze detaliile lipsă

Exemplu de intrare — POST /v1/agents/carla/tasks

{
  "type": "transport_request.extract",
  "input": {
    "channel": "email",
    "from": "mihai@agrodelta.example",
    "subject": "Truck Pitesti - Lyon",
    "body": "Hi, we need a truck from Pitești to Lyon next week, 14 europallets ~9t, not stackable. Can you send a price?"
  },
  "callback_url": "https://crm.yourcompany.example/hooks/aurora"
}

Exemplu de ieșire — transport_request.extract

{
  "transport_request": {
    "pickup": {
      "city": "Pitești",
      "country": "RO",
      "postcode": null,
      "date": null
    },
    "delivery": {
      "city": "Lyon",
      "country": "FR",
      "postcode": null
    },
    "cargo": {
      "pallet_type": "EUR",
      "pallets": 14,
      "stackable": false,
      "weight_kg": 9000,
      "loading_meters": 5.6,
      "adr": false
    },
    "missing_fields": [
      "pickup.date",
      "delivery.postcode"
    ],
    "language": "en",
    "confidence": 0.93
  }
}

Rio — Coordonator dispecerat și transportatori

ID agent rio, Operațiuni. Pagina agentului

Tip de sarcină	Ce face
`carrier.match`	Selectează transportatori pentru o încărcătură din propriile tale date
`carrier.request_offers`	Trimite cereri de preț transportatorilor și colectează răspunsurile
`shipment.update`	Procesează un eveniment de status, ETA sau întârziere și anunță persoanele potrivite
`documents.check`	Verifică dacă CMR-ul, POD-ul și fotografiile sunt complete

Exemplu de intrare — POST /v1/agents/rio/tasks

{
  "type": "carrier.match",
  "input": {
    "shipment_id": "SHP-5530",
    "lane": {
      "from": "RO-110",
      "to": "FR-69"
    },
    "vehicle": "tautliner",
    "max_buy_price": 1260
  }
}

Exemplu de ieșire — carrier.match

{
  "candidates": [
    {
      "carrier_id": "car_118",
      "name": "Carpat Trans SRL",
      "lane_loads_90d": 4,
      "last_price": 1190,
      "score": 0.91
    },
    {
      "carrier_id": "car_052",
      "name": "Dunav Freight EOOD",
      "lane_loads_90d": 2,
      "last_price": 1240,
      "score": 0.78
    }
  ],
  "recommended": "car_118"
}

Quinn — Specialistă oferte și prețuri

ID agent quinn, Vânzări și marketing. Pagina agentului

Tip de sarcină	Ce face
`quote.create`	Calculează prețul unei cereri și produce oferta
`quote.compare_offers`	Ordonează ofertele transportatorilor sau furnizorilor după regulile tale
`quote.follow_up`	Revine asupra ofertelor deschise și înregistrează motivele de câștig sau pierdere

Exemplu de intrare — POST /v1/agents/quinn/tasks

{
  "type": "quote.create",
  "input": {
    "transport_request_id": "REQ-2041",
    "pricing_rules": "default",
    "currency": "EUR",
    "formats": [
      "email",
      "pdf"
    ]
  }
}

Exemplu de ieșire — quote.create

{
  "quote": {
    "id": "Q-7781",
    "sell_price": 1560,
    "currency": "EUR",
    "breakdown": {
      "estimated_buy_price": 1240,
      "margin": 320
    },
    "margin_pct": 20.5,
    "valid_until": "2026-10-12T14:00:00Z",
    "approval_required": false,
    "files": [
      {
        "type": "pdf",
        "file_id": "file_q7781"
      }
    ]
  }
}

Victor — Specialist dezvoltare vânzări

ID agent victor, Vânzări și marketing. Pagina agentului

Tip de sarcină	Ce face
`lead.qualify`	Evaluează un lead față de profilul tău de client ideal
`lead.research`	Rezumă ce face o companie și de ce ar putea avea nevoie de tine
`outreach.draft`	Scrie un prim mesaj sau o secvență de revenire
`deal.next_step`	Sugerează și programează următoarea acțiune pentru o oportunitate

Exemplu de intrare — POST /v1/agents/victor/tasks

{
  "type": "lead.qualify",
  "input": {
    "lead": {
      "name": "Elena Radu",
      "company": "Nordic Pack SRL",
      "website": "https://nordicpack.example",
      "message": "We’re looking for a partner for weekly groupage to Germany."
    },
    "criteria": "default"
  }
}

Exemplu de ieșire — lead.qualify

{
  "qualification": {
    "score": 82,
    "fit": "high",
    "segment": "manufacturing",
    "reasons": [
      "recurring weekly volume",
      "lane matches RO to DE groupage"
    ],
    "next_step": {
      "type": "call_proposal",
      "draft_id": "drf_441"
    }
  }
}

Mara — Manager de marketing

ID agent mara, Vânzări și marketing. Pagina agentului

Tip de sarcină	Ce face
`content.plan`	Construiește un calendar de conținut pentru o perioadă și un obiectiv
`content.draft`	Scrie postări, newslettere, articole sau texte de reclamă
`seo.brief`	Pregătește un brief SEO cu intenția de căutare și structura
`review.reply`	Redactează un răspuns la o recenzie sau un comentariu

Exemplu de intrare — POST /v1/agents/mara/tasks

{
  "type": "content.draft",
  "input": {
    "format": "social_post",
    "channel": "linkedin",
    "topic": "Weekly groupage Romania to Germany",
    "audience": "operations managers in manufacturing",
    "language": "en",
    "variants": 2
  }
}

Exemplu de ieșire — content.draft

{
  "drafts": [
    {
      "id": "drf_901",
      "text": "Every Thursday a truck leaves Romania for Germany with room for your pallets…",
      "status": "waiting_for_approval"
    },
    {
      "id": "drf_902",
      "text": "Groupage to Germany shouldn’t mean waiting for a full truck…",
      "status": "waiting_for_approval"
    }
  ]
}

Sofia — Coordonatoare suport clienți

ID agent sofia, Relații cu clienții. Pagina agentului

Tip de sarcină	Ce face
`ticket.triage`	Clasifică un mesaj după subiect și urgență și îl rutează
`ticket.reply`	Răspunde unui mesaj de client cu date din sistemele tale
`claim.intake`	Deschide o reclamație și colectează documentele necesare

Exemplu de intrare — POST /v1/agents/sofia/tasks

{
  "type": "ticket.reply",
  "input": {
    "channel": "whatsapp",
    "contact": {
      "phone": "+40700000000"
    },
    "message": "Hello, where is our shipment to Lyon?",
    "context_lookup": true
  }
}

Exemplu de ieșire — ticket.reply

{
  "reply": {
    "text": "Hi Mihai! Your shipment SHP-5530 left Pitești on 14 October and is now near Dijon…",
    "language": "en",
    "sources": [
      "tms:shipment:SHP-5530"
    ]
  },
  "ticket": {
    "id": "T-9120",
    "status": "answered",
    "handover": false
  }
}

Ada — Asistentă contabilitate

ID agent ada, Financiar și achiziții. Pagina agentului

Tip de sarcină	Ce face
`invoice.extract`	Transformă o factură de furnizor în date structurate
`invoice.match`	Potrivește o factură cu comenzi, transporturi sau comenzi de achiziție
`payments.reconcile`	Reconciliază un extras bancar cu elementele deschise
`collections.remind`	Pregătește sau trimite un memento de plată

Exemplu de intrare — POST /v1/agents/ada/tasks

{
  "type": "invoice.extract",
  "input": {
    "file_id": "file_inv_4471",
    "match_against": [
      "orders",
      "shipments"
    ]
  }
}

Exemplu de ieșire — invoice.extract

{
  "invoice": {
    "supplier": {
      "name": "Carpat Trans SRL",
      "vat_id": "RO00000000"
    },
    "number": "4471",
    "issue_date": "2026-10-17",
    "currency": "EUR",
    "total": 1250.00,
    "lines": [
      {
        "description": "Transport Pitești–Lyon",
        "amount": 1210.00
      },
      {
        "description": "Waiting time",
        "amount": 40.00
      }
    ]
  },
  "match": {
    "shipment_id": "SHP-5530",
    "expected_total": 1210.00,
    "difference": 40.00,
    "status": "needs_review"
  }
}

Paul — Specialist achiziții

ID agent paul, Financiar și achiziții. Pagina agentului

Tip de sarcină	Ce face
`rfq.create`	Scrie și trimite o cerere de ofertă
`offers.compare`	Compară ofertele furnizorilor după criterii ponderate
`po.draft`	Redactează o comandă de achiziție pentru aprobare
`spend.analyze`	Defalcă cheltuielile pe categorii și furnizori

Exemplu de intrare — POST /v1/agents/paul/tasks

{
  "type": "offers.compare",
  "input": {
    "rfq_id": "rfq_311",
    "criteria": {
      "price": 0.5,
      "delivery": 0.3,
      "terms": 0.2
    }
  }
}

Exemplu de ieșire — offers.compare

{
  "ranking": [
    {
      "supplier": "Supplier C",
      "unit_price": 326,
      "delivery_days": 2,
      "includes_fitting": true,
      "score": 0.86
    },
    {
      "supplier": "Supplier A",
      "unit_price": 318,
      "delivery_days": 1,
      "includes_fitting": false,
      "score": 0.82
    },
    {
      "supplier": "Supplier B",
      "unit_price": 299,
      "delivery_days": 21,
      "includes_fitting": false,
      "score": 0.64
    }
  ],
  "recommendation": "Supplier C if fitting is needed; otherwise Supplier A."
}

Hugo — Partener HR și recrutare

ID agent hugo, Oameni și juridic. Pagina agentului

Tip de sarcină	Ce face
`job_ad.draft`	Scrie un anunț de angajare dintr-un brief scurt
`applications.organize`	Transformă CV-urile într-un singur tabel structurat — fără punctaje
`interview.schedule`	Propune și rezervă intervale pentru interviuri
`documents.expiry`	Listează permisele, certificatele și contractele care expiră curând

Exemplu de intrare — POST /v1/agents/hugo/tasks

{
  "type": "documents.expiry",
  "input": {
    "within_days": 60,
    "document_types": [
      "driving_licence",
      "adr_certificate",
      "tachograph_card",
      "contract"
    ]
  }
}

Exemplu de ieșire — documents.expiry

{
  "expiring": [
    {
      "employee_id": "emp_204",
      "document": "tachograph_card",
      "expires_on": "2026-11-28"
    },
    {
      "employee_id": "emp_118",
      "document": "tachograph_card",
      "expires_on": "2026-12-03"
    },
    {
      "employee_id": "emp_311",
      "document": "tachograph_card",
      "expires_on": "2026-12-09"
    }
  ],
  "notified": [
    "employees",
    "fleet_manager"
  ]
}

Lex — Asistent juridic și conformitate

ID agent lex, Oameni și juridic. Pagina agentului

Tip de sarcină	Ce face
`contract.review`	Verifică un contract după playbook-ul tău
`contract.draft`	Redactează un document din șablonul tău
`contract.compare`	Explică diferențele dintre două versiuni
`claim.prepare`	Alcătuiește un dosar de reclamație pentru daune sau întârziere
`gdpr.request`	Înregistrează și urmărește o cerere a persoanei vizate

Exemplu de intrare — POST /v1/agents/lex/tasks

{
  "type": "contract.review",
  "input": {
    "file_id": "file_nordic_fta",
    "playbook": "transport_client_v3"
  }
}

Exemplu de ieșire — contract.review

{
  "review": {
    "issues": [
      {
        "clause": "7.2",
        "topic": "payment_term",
        "found": "90 days",
        "playbook": "max 45 days",
        "severity": "high",
        "suggested_text": "Payment within 45 days of the invoice date."
      },
      {
        "clause": "9.3",
        "topic": "liability_cap",
        "found": "EUR 500 per shipment",
        "playbook": "CMR limits",
        "severity": "high"
      },
      {
        "clause": "15.1",
        "topic": "auto_renewal",
        "found": "3 years",
        "playbook": "max 1 year",
        "severity": "medium"
      }
    ],
    "escalate": [
      {
        "clause": "12",
        "reason": "exclusive foreign jurisdiction"
      }
    ]
  }
}

Iris — Analistă date și raportare

ID agent iris, Management. Pagina agentului

Tip de sarcină	Ce face
`data.ask`	Răspunde la o întrebare despre datele tale, cu surse
`report.generate`	Construiește un raport KPI programat
`anomaly.scan`	Caută mișcări neobișnuite în indicatorii tăi

Exemplu de intrare — POST /v1/agents/iris/tasks

{
  "type": "data.ask",
  "input": {
    "question": "Why is our margin lower this month?",
    "sources": [
      "erp",
      "tms"
    ],
    "period": "2026-10"
  }
}

Exemplu de ieșire — data.ask

{
  "answer": {
    "text": "Gross margin is 14.2% against 17.9% last month…",
    "figures": [
      {
        "metric": "gross_margin_pct",
        "value": 14.2,
        "previous": 17.9
      }
    ],
    "sources": [
      "erp:invoices",
      "tms:shipments"
    ],
    "suggested_actions": [
      {
        "agent_id": "ada",
        "type": "collections.remind",
        "note": "invoice unbilled waiting time"
      }
    ]
  }
}

Atlas — Șef de cabinet

ID agent atlas, Management. Pagina agentului

Tip de sarcină	Ce face
`task.route`	Înțelege o cerere și o trimite agentului potrivit
`brief.generate`	Pregătește un briefing de management pentru o perioadă
`meeting.summarize`	Transformă notițe sau o transcriere în decizii și sarcini
`followups.track`	Listează punctele deschise și le urmărește responsabilii

Exemplu de intrare — POST /v1/agents/atlas/tasks

{
  "type": "brief.generate",
  "input": {
    "period": "yesterday",
    "audience": "management",
    "agents": [
      "carla",
      "quinn",
      "rio",
      "ada",
      "paul",
      "lex"
    ]
  }
}

Exemplu de ieșire — brief.generate

{
  "brief": {
    "summary": "Yesterday: 38 transport requests, 21 quotes sent, 14 accepted.",
    "needs_decision": [
      {
        "ref": "PO-1204",
        "agent_id": "paul",
        "action": "approve purchase order"
      },
      {
        "ref": "contract_nordic_fta",
        "agent_id": "lex",
        "action": "sign off contract check"
      },
      {
        "ref": "client_agro_delta",
        "agent_id": "quinn",
        "action": "framework price"
      }
    ]
  }
}

Securitate și date

În tranzit și în repaus: tot traficul folosește TLS; datele stocate sunt criptate în repaus.
Utilizarea datelor tale: intrările, ieșirile și documentele tale sunt prelucrate doar pentru a-ți executa sarcinile și a furniza serviciul. Nu sunt folosite pentru antrenarea modelelor AI.
Retenție: intrările și ieșirile sarcinilor sunt păstrate implicit 90 de zile. Setează o perioadă mai scurtă în consolă — sau zero, ca să fie șterse imediat după livrare. Firele, sarcinile și documentele pot fi șterse oricând prin API.
Acces: chei cu permisiuni restrânse, limite per cheie și un jurnal al cererilor, cu cheia și id-ul cererii pentru fiecare apel.
Protecția datelor: prelucrăm datele personale în numele tău, conform termenilor de prelucrare a datelor din abonament.

Istoric modificări

2026-10-01

Prima versiune publică a API-ului: agenți, sarcini, fire de discuție și mesaje cu streaming, instrumente, cunoștințe, predări, webhookuri, consum și limite, facturare și facturi.