Documentazione API

Aurora Agents API

Tutto ciò che serve ai tuoi sviluppatori per collegare gli agenti AI di Aurora al tuo CRM, ERP o TMS: autenticazione, attività, conversazioni, strumenti, webhook, limiti di token e fatturazione.

Guida rapida Riferimento agenti

Introduzione

L’API di Aurora permette al tuo CRM, ERP, TMS o a qualsiasi backend di affidare lavoro agli agenti AI di Aurora e ricevere risultati strutturati. Ogni agente ha un insieme fisso di tipi di attività con input documentati e output JSON, così il tuo sistema può contare sulla forma di ciò che riceve.

BASEhttps://api.auroraaisystems.com/v1

Formato: JSON su HTTPS, UTF-8. Invia Content-Type: application/json con ogni corpo della richiesta.
Orari: ISO 8601 in UTC, es. 2026-10-09T08:14:03Z. I mesi di fatturazione iniziano alle 00:00 UTC del giorno 1.
ID: con prefisso per tipo di oggetto — task_, thr_, msg_, tool_, doc_, whk_, evt_, inv_. Gli agenti usano id leggibili come carla.
Importi: valori decimali in EUR, es. 699.00.
ID richiesta: ogni risposta contiene l’header Aurora-Request-Id. Indicalo quando contatti il supporto.

Gli agenti

ID agente	Agente	Tipi di attività principali
carla	Carla — Coordinatrice delle richieste di trasporto	`transport_request.extract`, `transport_request.qualify`
rio	Rio — Coordinatore di dispatching e vettori	`carrier.match`, `carrier.request_offers`
quinn	Quinn — Specialista di preventivi e prezzi	`quote.create`, `quote.compare_offers`
victor	Victor — Sales Development Representative	`lead.qualify`, `lead.research`
mara	Mara — Marketing manager	`content.plan`, `content.draft`
sofia	Sofia — Responsabile del supporto clienti	`ticket.triage`, `ticket.reply`
ada	Ada — Assistente contabile	`invoice.extract`, `invoice.match`
paul	Paul — Specialista acquisti	`rfq.create`, `offers.compare`
hugo	Hugo — Partner HR e recruiting	`job_ad.draft`, `applications.organize`
lex	Lex — Assistente legale e compliance	`contract.review`, `contract.draft`
iris	Iris — Analista dati e reporting	`data.ask`, `report.generate`
atlas	Atlas — Capo di gabinetto	`task.route`, `brief.generate`

Account, agenti e integrazioni vengono configurati con te durante l’onboarding. Le chiavi di test vengono emesse dopo il kickoff e quelle live alla messa in produzione. Fino ad allora, tutto ciò che c’è in questa pagina si può provare in sandbox.

Guida rapida

Quattro passi da un’email nella casella a un record strutturato nel tuo CRM.

1. Salva la chiave di test

Conserva le chiavi sul tuo server, come variabile d’ambiente. Non metterle mai in un browser, in un’app mobile o in un repository pubblico.

Terminale

export AURORA_API_KEY="aur_test_…"

2. Crea un’attività

Chiedi a Carla di trasformare l’email di un cliente in una richiesta di trasporto. Il campo metadata torna invariato, così puoi abbinare il risultato al record del 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. Ottieni il risultato

Registra un webhook e ricevi task.completed, oppure interroga l’attività finché il suo stato non è definitivo.

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. Usalo

Scrivi output.transport_request nel record del CRM. Carla ha anche passato automaticamente la richiesta a Quinn — il suo preventivo arriva come un altro evento task.completed quando il cliente ha inviato i dettagli mancanti.

Autenticazione

Autentica ogni richiesta con una chiave segreta nell’header Authorization.

Header HTTP

Authorization: Bearer aur_live_4f9c…

Prefisso della chiave	Ambiente	Comportamento
`aur_test_`	Sandbox	Stessi agenti e stessa API. 500.000 token gratuiti al mese. Chiamate agli strumenti e webhook vanno ai tuoi endpoint di test. Mai fatturato.
`aur_live_`	Produzione	Lavoro reale, misurato e fatturato. Emessa alla messa in produzione.

Ambiti e restrizioni

Ogni chiave può essere limitata a specifici ambiti e agenti e avere un proprio limite mensile di token. Ambiti disponibili: agents:read, agents:write, tasks:read, tasks:write, threads:write, tools:write, knowledge:write, webhooks:write, usage:read, limits:write, billing:read.

Crea, limita e ruota le chiavi dalla console. Una chiave revocata smette subito di funzionare.
Per un widget di chat sul tuo sito, chiama Aurora dal tuo backend — mai dal browser del visitatore.
Una chiave mancante o non valida restituisce 401 authentication_error; una chiave senza l’ambito giusto restituisce 403 permission_denied.

Concetti di base

Oggetto	Che cos’è
Agente	Un lavoratore AI configurato con un solo compito. Il suo manifest unisce persona, competenze, strumenti, conoscenza, protezioni e limiti.
Attività	Un’unità di lavoro per un agente: un tipo, un input e, al termine, un output JSON. Le attività vengono eseguite in modo asincrono.
Thread e messaggio	Una conversazione — una chat di supporto, uno scambio su WhatsApp. Il thread conserva la cronologia; ogni messaggio riceve la risposta dell’agente.
Strumento	Un’azione nei tuoi sistemi che un agente può richiamare, come trovare un cliente o creare un ordine.
Documento di conoscenza	Un file o un testo su cui l’agente può basarsi: tariffe, condizioni, policy, modelli.
Passaggio di consegne	Il passaggio di un risultato finito all’agente successivo, in automatico o dopo la tua conferma.
Consumi e limiti	Token misurati a ogni chiamata al modello; determinano avvisi, limiti e la voce dei token extra in fattura.
Evento	Una notifica webhook che qualcosa è successo — un’attività completata, un limite raggiunto, una fattura pagata.

Agenti

L’oggetto agente è il manifest dell’agente: come suona, cosa sa fare, cosa può toccare e dove si ferma. Puoi leggere tutto; puoi modificare persona, stato e limiti.

L’oggetto agente

Oggetto agente

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

Parametro	Descrizione
id string	Id leggibile dell’agente, es. `carla`. Non cambia mai, anche se rinomini l’agente.
status enum	`active`, `paused` o `configuring`. Gli agenti in pausa rifiutano nuove attività con `409`.
persona object	Nome visualizzato, tratti, tono (formalità 1–5), lingue, se rispondere nella lingua del mittente e firma.
skills array	Tipi di attività che questo agente esegue. Vedi il riferimento agenti.
tools array	Nomi degli strumenti che questo agente può richiamare.
knowledge array	Raccolte di conoscenza che l’agente può usare.
guardrails object	Cosa l’agente non fa mai e quando passa la mano a una persona. Sola lettura.
handoffs array	Quale risultato va a quale agente, e come. Sola lettura.
limits object	Limite mensile di token per questo agente (o `null` per il pool condiviso) e numero massimo di token di output per chiamata al modello.

Elenca gli agenti

GET/v1/agents

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

Recupera un agente

GET/v1/agents/{agent_id}

Aggiorna un agente

PATCH/v1/agents/{agent_id}

Tramite API si possono modificare solo i campi qui sotto. Competenze, strumenti, protezioni e passaggi di consegne si modificano insieme al nostro team, così ogni modifica viene testata in sandbox prima di arrivare ai tuoi clienti.

Parametro	Descrizione
persona.display_name string	Il nome che vedono i clienti, es. se rinomini Carla per adattarla al tuo brand.
persona.tone.formality integer 1–5	1 è molto formale, 5 molto informale.
persona.languages array	Codici ISO 639-1 delle lingue in cui scrive l’agente, es. `["en","ro","de"]`.
persona.reply_in_sender_language boolean	Rispondi nella lingua del messaggio ricevuto, se è nell’elenco.
persona.signature string	Formula di chiusura usata nei messaggi in uscita, fino a 60 caratteri.
status enum	`active` o `paused`.
limits.monthly_token_limit integer o null	Tetto mensile per questo agente all’interno del tuo pool.
limits.max_output_tokens integer	Fino a 4.000, salvo diverso accordo.

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

Attività

Un’attività è un’unità di lavoro per un agente. Le attività sono asincrone: ne crei una, poi ricevi il risultato via webhook o tramite polling.

Crea un’attività

POST/v1/agents/{agent_id}/tasks

Parametro	Descrizione
type string obbligatorio	Un tipo di attività supportato dall’agente, es. `transport_request.extract`.
input object obbligatorio	Input per il tipo di attività. I campi per tipo sono elencati nel riferimento agenti; un input non valido restituisce `422`.
metadata object	Fino a 20 coppie chiave–valore restituite invariate, es. l’id del record nel tuo CRM.
callback_url string	Invia gli eventi di questa attività a questo URL invece che ai webhook registrati.
thread_id string	Collega l’attività a una conversazione così l’agente ne vede la cronologia.
priority enum	`normal` (predefinito) o `high`.
handoff enum	`auto`, `suggest` o `none`. Per impostazione predefinita, quello del manifest dell’agente.
max_output_tokens integer	Riduce il limite di output per questa attività.

Invia un header Idempotency-Key così una richiesta ripetuta non crea mai un’attività duplicata. La risposta è 202 Accepted con l’attività in stato queued.

L’oggetto attività

Oggetto attività

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

Stati delle attività

Stato	Significato
`queued`	Accettata e in attesa di esecuzione.
`running`	L’agente ci sta lavorando.
`requires_action`	L’agente ha richiamato uno strumento in modalità client e attende il tuo risultato. Vedi invio dei risultati degli strumenti.
`completed`	Completata; `output` contiene il risultato.
`escalated`	Una protezione ha passato il lavoro a una persona. `escalation` contiene il motivo e un riepilogo per il tuo team.
`failed`	Non è stato possibile completarla; `error` spiega perché. I fallimenti causati da noi non vengono fatturati.
`cancelled`	Annullata da te. I token già usati vengono fatturati.

Recupera un’attività

GET/v1/tasks/{task_id}

Elenca le attività

GET/v1/tasks

Parametro	Descrizione
agent_id string	Solo le attività di questo agente.
status enum	Solo le attività in questo stato.
type string	Solo questo tipo di attività.
created_after / created_before timestamp	Intervallo di tempo.
limit / cursor integer / string	Vedi paginazione.

Invia i risultati degli strumenti

POST/v1/tasks/{task_id}/tool_outputs

Quando un agente richiama uno strumento registrato in modalità client, l’attività si ferma in requires_action e ricevi task.requires_action:

Attività in attesa del risultato del tuo strumento

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

Annulla un’attività

POST/v1/tasks/{task_id}/cancel

Le attività in queued, running o requires_action possono essere annullate. I token già usati vengono fatturati.

Messaggi e thread

Usa i thread per le conversazioni — una chat di supporto, uno scambio su WhatsApp, un assistente interno. Il thread conserva la cronologia; ogni messaggio inviato restituisce la risposta dell’agente.

Crea un thread

POST/v1/threads

Parametro	Descrizione
agent_id string obbligatorio	L’agente a cui appartiene la conversazione, es. `sofia`.
channel enum	`chat`, `email`, `whatsapp` o `internal`. Determina formattazione e lunghezza.
contact object	Nome, email e telefono di chi scrive. Usati per cercare i dati che l’agente può condividere con questa persona.
metadata object	Restituito invariato.

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

Invia un messaggio

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

Risposta dell’agente

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

Se handover è true, l’agente si è fermato e deve continuare una persona; il contenuto del messaggio lo comunica al cliente e task.escalated contiene il riepilogo per il tuo team.

Streaming

Imposta "stream": true per ricevere la risposta come server-sent events (text/event-stream) mentre viene scritta. Eventi: message.delta, message.completed ed error.

Flusso di eventi

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

Elenca i messaggi ed elimina un thread

GET/v1/threads/{thread_id}/messages

DELETE/v1/threads/{thread_id}

Eliminare un thread lo rimuove definitivamente con tutti i suoi messaggi.

Strumenti

Gli strumenti permettono agli agenti di agire nei tuoi sistemi. Descrivi un’azione con un JSON Schema; l’agente decide quando richiamarla e con quali argomenti. Nei tuoi sistemi non viene eseguito nulla se non registri uno strumento per farlo.

Registra uno strumento

POST/v1/tools

Parametro	Descrizione
name string obbligatorio	Nome univoco, es. `crm.find_customer`. Lettere, cifre, punti e underscore.
description string obbligatorio	Cosa fa lo strumento e quando usarlo. Gli agenti lo leggono, quindi sii preciso.
input_schema object obbligatorio	JSON Schema per gli argomenti.
mode enum obbligatorio	`webhook`: chiamiamo noi il tuo URL. `client`: l’attività si ferma ed esegui tu lo strumento.
url string	Obbligatorio in modalità webhook. Solo HTTPS.
agents array obbligatorio	Id degli agenti autorizzati a richiamare lo strumento.
timeout_ms integer	Quanto attendiamo la tua risposta in modalità webhook. Predefinito 10.000, massimo 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
    }
  }'

Modalità webhook

Inviamo un POST firmato al tuo URL — stesso schema di firma dei webhook — e attendiamo la tua risposta JSON.

Noi inviamo

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

Tu rispondi (200 OK)

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

Se il tuo endpoint restituisce un errore o va in timeout, l’agente viene informato che lo strumento è fallito. Riprova una volta, prosegue senza il risultato se può farlo in sicurezza oppure esegue l’escalation dell’attività.

Modalità client

L’attività si ferma con stato requires_action. Esegui tu l’azione e invia il risultato con invio dei risultati degli strumenti. Usa la modalità client quando il tuo sistema non può ricevere chiamate in ingresso.

Elenca ed elimina strumenti

GET/v1/tools

DELETE/v1/tools/{tool_id}

Conoscenza

Carica i documenti su cui gli agenti devono basarsi — listini, condizioni, policy, modelli, casi passati. Quando un agente lavora a un’attività, recupera i passaggi rilevanti e usa i tuoi fatti invece della conoscenza generale.

Carica un documento

POST/v1/knowledge/documents

Parametro	Descrizione
file file	PDF, DOCX, XLSX, CSV, TXT, MD o HTML, fino a 50 MB. Invia come `multipart/form-data`.
url / text string	Invece di un file, un URL pubblico da scaricare o testo semplice, in JSON.
title string obbligatorio	Mostrato nella console e tra le fonti dell’agente.
agents array obbligatorio	Id degli agenti che possono usare il documento.
collection string	Raggruppa i documenti, es. `kb_lanes`.

cURL — caricamento 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"
}

Lo stato passa da processing a ready o failed e ricevi knowledge.document.ready o knowledge.document.failed. Caricamento e indicizzazione sono gratuiti; i passaggi usati in un’attività contano come token di input.

Elenca, recupera ed elimina

GET/v1/knowledge/documents

GET/v1/knowledge/documents/{document_id}

DELETE/v1/knowledge/documents/{document_id}

Eliminare un documento rimuove il file e il suo indice; gli agenti smettono di usarlo.

Passaggi di consegne

Gli agenti si passano il lavoro come fa il tuo team: Carla completa una richiesta di trasporto, Quinn la prezza, Rio prenota il vettore. I passaggi sono definiti nel manifest di ogni agente e concordati con te durante l’attivazione.

Modalità	Cosa succede
`auto`	L’attività successiva viene creata automaticamente, con l’output finito come input.
`suggest`	L’output include `suggested_handoffs`; non succede nulla finché non confermi.
`none`	Nessun passaggio; decide il tuo sistema cosa viene dopo.

Conferma un passaggio suggerito

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

Ogni passaggio viene registrato nell’array handoffs dell’attività padre e nel parent_task_id dell’attività figlia, e genera handoff.created. Atlas può coordinare catene più lunghe per te.

Webhook

I webhook inviano gli eventi al tuo sistema appena accadono, così non devi interrogare.

Registra 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 — il segreto viene mostrato una sola volta

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

Eventi

Evento	Inviato quando
`task.completed`	Un’attività è terminata con un output.
`task.failed`	Un’attività non è stata completata.
`task.requires_action`	Un’attività attende il risultato del tuo strumento.
`task.escalated`	Una protezione ha passato un’attività a una persona.
`handoff.created`	Un agente ha passato il lavoro a un altro agente.
`message.completed`	Un agente ha completato una risposta in un thread.
`knowledge.document.ready`	Un documento è indicizzato e in uso.
`knowledge.document.failed`	Un documento non è stato elaborato.
`usage.threshold_reached`	Il consumo ha superato una delle tue soglie di avviso.
`limit.reached`	È stato raggiunto un limite di token o un tetto di spesa.
`invoice.created`	È stata emessa una nuova fattura.
`invoice.paid`	Una fattura è stata pagata.
`invoice.payment_failed`	Un pagamento automatico non è andato a buon fine.
`agent.updated`	Sono cambiati persona, stato o limiti di un agente.

Payload

Envelope dell’evento

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

Verifica delle firme

Ogni webhook e ogni chiamata a uno strumento in modalità webhook contiene l’header Aurora-Signature, es. t=1760000043,v1=6c1f…. Calcola un HMAC-SHA256 con il segreto dell’endpoint su {t}.{raw body}, confrontalo in tempo costante con v1 e rifiuta le richieste più vecchie di 5 minuti.

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);
}

Consegna e nuovi tentativi

Rispondi con uno stato 2xx entro 10 secondi, poi esegui il lavoro pesante in background. Altrimenti riproviamo con backoff esponenziale per un massimo di 24 ore. Gli eventi possono arrivare più volte o fuori ordine — salva l’id dell’evento e ignora i duplicati.

Consumi e limiti di token

Ogni chiamata al modello fatta per le tue attività viene misurata in token. Il consumo determina avvisi, limiti e la voce dei token extra in fattura.

Come si contano i token

Token di input: istruzioni e persona dell’agente, input dell’attività, cronologia della conversazione, passaggi di conoscenza recuperati e risultati degli strumenti.
Token di output: tutto ciò che scrive l’agente, compresi gli argomenti delle chiamate agli strumenti.
Il consumo di un’attività è la somma di tutte le sue chiamate al modello. Token di input e di output hanno lo stesso prezzo.
Ogni agente include 10.000.000 di token al mese, condivisi tra i tuoi agenti e azzerati alle 00:00 UTC del giorno 1. I token extra costano 15 € per milione, misurati ogni 1.000.
Caricare e indicizzare la conoscenza è gratuito. Le attività che falliscono per un errore da parte nostra non vengono fatturate.

Ogni attività e ogni messaggio restituisce un oggetto usage, e ogni risposta contiene questi header:

Header	Valore
`Aurora-Tokens-Used`	Token usati da questa richiesta.
`Aurora-Tokens-Remaining`	Token inclusi rimasti nel mese di fatturazione corrente, sull’intero account.
`Aurora-Spend-Remaining`	EUR rimanenti prima del tetto di spesa, quando la policy è `cap`.

Recupera i consumi

GET/v1/usage

Parametro	Descrizione
period YYYY-MM	Mese di fatturazione. Per impostazione predefinita, quello corrente.
group_by enum	`agent` (predefinito), `api_key` o `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"
}

Limiti

I limiti decidono cosa succede quando i token inclusi finiscono e impediscono a un singolo agente o a un’integrazione di consumare tutto il pool. Imposti la policy al checkout e puoi cambiarla in qualsiasi momento; le modifiche hanno effetto immediato.

L’oggetto limiti

GET/v1/limits

Oggetto limiti

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

Aggiorna i limiti

PATCH/v1/limits

Parametro	Descrizione
overage_policy enum	`hard_stop`: stop ai token inclusi. `cap`: consenti token extra fino a `monthly_spend_cap_eur`. `unlimited`: consenti token extra senza tetto.
monthly_spend_cap_eur number	Spesa massima mensile per token extra, IVA esclusa. Usato con `cap`.
alert_thresholds_pct array	Percentuali dei token inclusi che attivano `usage.threshold_reached`.
alert_emails array	Chi riceve le email di avviso.
agents.{agent_id}.monthly_token_limit integer o null	Limite mensile per un agente.
api_keys.{key_id}.monthly_token_limit integer o null	Limite mensile per una chiave 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
      }
    }
  }'

I limiti di frequenza sono in sola lettura; contattaci per aumentarli.

Quando si raggiunge un limite

Situazione	Risposta
Token inclusi esauriti e policy `hard_stop`	`402` con codice `quota_exceeded`
Tetto di spesa raggiunto (policy `cap`)	`402` con codice `spend_cap_reached`
Limite mensile di un agente raggiunto	`402` con codice `agent_limit_reached`, solo per quell’agente
Limite mensile di una chiave API raggiunto	`402` con codice `key_limit_reached`, solo per quella chiave

Le attività già in corso terminano normalmente. Nuove attività e messaggi vengono rifiutati fino al mese di fatturazione successivo o finché non alzi il limite. Un evento limit.reached viene inviato una volta per limite al mese.

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

Fatturazione e fatture

Leggi l’abbonamento, visualizza in anteprima la prossima fattura e scarica le fatture — per esempio per registrarle automaticamente nel tuo ERP.

Il costo di attivazione viene fatturato all’ordine.
Gli abbonamenti partono alla messa in produzione; il primo mese è calcolato pro rata al giorno.
Il giorno 1 di ogni mese viene emessa un’unica fattura: abbonamenti del nuovo mese in anticipo, token extra del mese precedente a consuntivo e, per i pagamenti con carta, la commissione del processore riaddebitata al costo, ove consentito.
Carta e addebito diretto SEPA vengono addebitati automaticamente alla data della fattura; i bonifici scadono entro 14 giorni.
Per le aziende rumene, le fatture vengono trasmesse anche tramite e-Factura.

Abbonamento

GET/v1/billing/subscription

Oggetto abbonamento

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

Aggiungi o rimuovi agenti

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

L’agente viene aggiunto nello stato configuring e diventa attivo una volta configurato per te; la fatturazione parte all’attivazione, pro rata. Se serve una nuova integrazione, ne confermiamo prima il perimetro con te.

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

Rimuove l’agente alla fine del mese di fatturazione in corso.

Prossima fattura

GET/v1/billing/upcoming

Anteprima della fattura

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

Fatture

GET/v1/billing/invoices

GET/v1/billing/invoices/{invoice_id}

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

Oggetto fattura

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

Parametro	Descrizione
number string	Serie e numero come emessi dal nostro sistema di fatturazione.
status enum	`open`, `paid`, `overdue` o `void`.
payment object	Metodo e stato del pagamento automatico, se presente.
e_invoice object o null	Per le aziende rumene: `pending`, `sent`, `accepted` o `rejected` in e-Factura.

Errori

Gli errori usano codici di stato HTTP standard e un corpo JSON coerente.

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

Stato	Tipo	Quando
400	`invalid_request_error`	JSON malformato, parametro sconosciuto o tipo errato.
401	`authentication_error`	Chiave API mancante, non valida o revocata.
402	`limit_error`	È stato raggiunto un limite di token o un tetto di spesa. `code` indica quale.
403	`permission_denied`	Alla chiave manca l’ambito o l’accesso all’agente per questa richiesta.
404	`not_found`	L’oggetto non esiste o non è visibile per questa chiave.
409	`conflict`	Chiave di idempotenza riutilizzata con un corpo diverso, oppure lo stato dell’oggetto non consente l’azione.
413	`payload_too_large`	Corpo della richiesta o file oltre il limite di dimensione.
422	`validation_error`	L’input non corrisponde allo schema del tipo di attività; `param` indica il campo.
429	`rate_limit_error`	Troppe richieste o token al minuto.
500	`api_error`	Qualcosa è andato storto da parte nostra. Puoi riprovare in sicurezza con la stessa Idempotency-Key.
503	`overloaded`	Problema temporaneo di capacità. Riprova con backoff.

Ogni errore include un request_id. Invialo a support@auroraaisystems.com se hai bisogno di aiuto.

Limiti di frequenza

Per impostazione predefinita ogni agente accetta 60 richieste e 200.000 token al minuto sul tuo account. Limiti più alti disponibili su richiesta.

Header	Significato
`RateLimit-Limit`	Richieste consentite nella finestra corrente.
`RateLimit-Remaining`	Richieste rimanenti nella finestra.
`RateLimit-Reset`	Secondi al reset della finestra.
`Retry-After`	Inviato con 429: secondi da attendere prima di riprovare.

Riprova 429 e 503 con backoff esponenziale e jitter. Non riprovare altri errori 4xx senza modificare la richiesta.

Idempotenza

Invia un header Idempotency-Key — qualsiasi stringa univoca, come un UUID — con le richieste POST. Se la stessa chiave arriva di nuovo entro 24 ore con lo stesso corpo, ricevi la risposta originale invece di un’attività duplicata. La stessa chiave con un corpo diverso restituisce 409 conflict.

Paginazione

Gli endpoint di elenco restituiscono pagine fino a 100 oggetti (predefinito 20). Passa limit e, per la pagina successiva, cursor.

Risposta di elenco

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

Versionamento

Fissa una versione con l’header Aurora-Version, es. Aurora-Version: 2026-10-01. Senza header si usa la versione del tuo account, impostata alla messa in produzione. Le modifiche incompatibili arrivano solo in nuove versioni datate, annunciate nel registro delle modifiche. Nuovi campi, tipi di evento e tipi di attività possono comparire in qualsiasi momento, quindi ignora i campi che non riconosci.

Riferimento agenti

Tipi di attività e payload di esempio per ogni agente. I campi di input e gli schemi di output esatti per il tuo account — compresi i campi aggiunti per i tuoi sistemi durante l’attivazione — sono disponibili nella console e tramite GET /v1/agents/{agent_id}.

Carla — Coordinatrice delle richieste di trasporto

ID agente carla, Operazioni. Pagina dell’agente

Tipo di attività	Cosa fa
`transport_request.extract`	Trasforma un’email, un messaggio o un documento in una richiesta di trasporto strutturata
`transport_request.qualify`	Verifica completezza e compatibilità con le tue tratte e regole
`transport_request.follow_up`	Prepara o invia il messaggio che chiede al cliente i dettagli mancanti

Esempio di input — 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"
}

Esempio di output — 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 — Coordinatore di dispatching e vettori

ID agente rio, Operazioni. Pagina dell’agente

Tipo di attività	Cosa fa
`carrier.match`	Seleziona una rosa di vettori per un carico dai tuoi dati
`carrier.request_offers`	Invia richieste di prezzo ai vettori e raccoglie le risposte
`shipment.update`	Elabora un evento di stato, ETA o ritardo e avvisa le persone giuste
`documents.check`	Verifica la completezza di CMR, POD e foto

Esempio di input — 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
  }
}

Esempio di output — 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 — Specialista di preventivi e prezzi

ID agente quinn, Vendite e marketing. Pagina dell’agente

Tipo di attività	Cosa fa
`quote.create`	Prezza una richiesta e produce l’offerta
`quote.compare_offers`	Classifica le offerte di vettori o fornitori secondo le tue regole
`quote.follow_up`	Sollecita le offerte aperte e registra i motivi di vittoria o perdita

Esempio di input — POST /v1/agents/quinn/tasks

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

Esempio di output — 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 — Sales Development Representative

ID agente victor, Vendite e marketing. Pagina dell’agente

Tipo di attività	Cosa fa
`lead.qualify`	Valuta un lead rispetto al tuo profilo di cliente ideale
`lead.research`	Riassume cosa fa un’azienda e perché potrebbe aver bisogno di te
`outreach.draft`	Scrive un primo messaggio o una sequenza di follow-up
`deal.next_step`	Suggerisce e pianifica la prossima azione su un’opportunità

Esempio di input — 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"
  }
}

Esempio di output — 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 — Marketing manager

ID agente mara, Vendite e marketing. Pagina dell’agente

Tipo di attività	Cosa fa
`content.plan`	Crea un calendario editoriale per un periodo e un obiettivo
`content.draft`	Scrive post, newsletter, articoli o testi pubblicitari
`seo.brief`	Prepara un brief SEO con intento di ricerca e struttura
`review.reply`	Prepara una risposta a una recensione o a un commento

Esempio di input — 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
  }
}

Esempio di output — 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 — Responsabile del supporto clienti

ID agente sofia, Servizio clienti. Pagina dell’agente

Tipo di attività	Cosa fa
`ticket.triage`	Classifica un messaggio per argomento e urgenza e lo instrada
`ticket.reply`	Risponde a un messaggio del cliente con dati dai tuoi sistemi
`claim.intake`	Apre un reclamo e raccoglie i documenti necessari

Esempio di input — 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
  }
}

Esempio di output — 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 — Assistente contabile

ID agente ada, Finanza e acquisti. Pagina dell’agente

Tipo di attività	Cosa fa
`invoice.extract`	Trasforma una fattura fornitore in dati strutturati
`invoice.match`	Abbina una fattura a ordini, spedizioni o ordini d’acquisto
`payments.reconcile`	Riconcilia un estratto conto con le partite aperte
`collections.remind`	Prepara o invia un sollecito di pagamento

Esempio di input — POST /v1/agents/ada/tasks

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

Esempio di output — 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 — Specialista acquisti

ID agente paul, Finanza e acquisti. Pagina dell’agente

Tipo di attività	Cosa fa
`rfq.create`	Scrive e invia una richiesta di offerta
`offers.compare`	Confronta le offerte dei fornitori secondo criteri ponderati
`po.draft`	Prepara un ordine d’acquisto per l’approvazione
`spend.analyze`	Scompone la spesa per categoria e fornitore

Esempio di input — POST /v1/agents/paul/tasks

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

Esempio di output — 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 — Partner HR e recruiting

ID agente hugo, Persone e legale. Pagina dell’agente

Tipo di attività	Cosa fa
`job_ad.draft`	Scrive un annuncio di lavoro da un breve brief
`applications.organize`	Trasforma i CV in un’unica tabella strutturata — senza punteggi
`interview.schedule`	Propone e prenota gli orari dei colloqui
`documents.expiry`	Elenca patenti, certificati e contratti in scadenza

Esempio di input — POST /v1/agents/hugo/tasks

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

Esempio di output — 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 — Assistente legale e compliance

ID agente lex, Persone e legale. Pagina dell’agente

Tipo di attività	Cosa fa
`contract.review`	Verifica un contratto rispetto al tuo playbook
`contract.draft`	Prepara un documento dal tuo modello
`contract.compare`	Spiega le differenze tra due versioni
`claim.prepare`	Compone una pratica di reclamo per danni o ritardi
`gdpr.request`	Registra e segue una richiesta dell’interessato

Esempio di input — POST /v1/agents/lex/tasks

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

Esempio di output — 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 — Analista dati e reporting

ID agente iris, Management. Pagina dell’agente

Tipo di attività	Cosa fa
`data.ask`	Risponde a una domanda sui tuoi dati, con le fonti
`report.generate`	Crea un report KPI programmato
`anomaly.scan`	Cerca movimenti insoliti nelle tue metriche

Esempio di input — POST /v1/agents/iris/tasks

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

Esempio di output — 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 — Capo di gabinetto

ID agente atlas, Management. Pagina dell’agente

Tipo di attività	Cosa fa
`task.route`	Comprende una richiesta e la invia all’agente giusto
`brief.generate`	Prepara un brief per il management relativo a un periodo
`meeting.summarize`	Trasforma note o una trascrizione in decisioni e attività
`followups.track`	Elenca le questioni aperte e sollecita i responsabili

Esempio di input — POST /v1/agents/atlas/tasks

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

Esempio di output — 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"
      }
    ]
  }
}

Sicurezza e dati

In transito e a riposo: tutto il traffico usa TLS; i dati archiviati sono cifrati a riposo.
Uso dei tuoi dati: input, output e documenti vengono trattati solo per svolgere le tue attività e fornire il servizio. Non vengono usati per addestrare modelli AI.
Conservazione: input e output delle attività sono conservati per 90 giorni per impostazione predefinita. Imposta un periodo più breve nella console — o zero, per eliminarli subito dopo la consegna. Thread, attività e documenti si possono eliminare in qualsiasi momento tramite l’API.
Accesso: chiavi con ambiti, limiti per chiave e un registro delle richieste con chiave e id richiesta per ogni chiamata.
Protezione dei dati: trattiamo i dati personali per tuo conto secondo le condizioni sul trattamento dei dati dell’abbonamento.

Registro delle modifiche

2026-10-01

Prima versione pubblica dell’API: agenti, attività, thread e messaggi con streaming, strumenti, conoscenza, passaggi di consegne, webhook, consumi e limiti, fatturazione e fatture.