Documentazione API

L’API Regunow usa HTTPS, autenticazione Bearer e il prefisso versionato /api/v1. La documentazione è consultabile senza account. Le richieste API richiedono accesso Pro attivo e accettazione delle politiche vigenti.

1. Accedi a Regunow e crea una chiave in Impostazioni → Chiavi API.
2. Conserva il segreto in modo sicuro. Viene mostrato una sola volta, alla creazione della chiave.
3. Imposta host e chiave, poi invia la prima domanda da un backend o da un’automazione affidabile.

# Use your Regunow host and a key from Settings → API Keys.
export REGUNOW_BASE_URL="https://YOUR_REGUNOW_HOST"
export REGUNOW_API_KEY="YOUR_API_KEY"

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-question-001" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Which EU product-safety obligations apply to a connected consumer device?"
    }],
    "mode": "jurisdiction",
    "jurisdiction": "eu"
  }'

La risposta si trova in output.content. Include i riferimenti alle fonti e i crediti addebitati. Questa richiesta consuma crediti. Usa una nuova chiave di idempotenza per ogni nuova domanda.

// Node.js: set REGUNOW_BASE_URL and REGUNOW_API_KEY in your environment.
// Generate one key per operation; keep it unchanged when retrying that operation.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();
const response = await fetch(
  process.env.REGUNOW_BASE_URL + "/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.REGUNOW_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "Summarize EU product-safety obligations." }],
      mode: "jurisdiction",
      jurisdiction: "eu",
    }),
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error.code + ": " + result.error.message);
}
console.log(result.output.content);

Invia la chiave API nell’intestazione HTTP Authorization di ogni richiesta. Le chiavi negli URL, nei cookie o nei corpi delle richieste non sono accettate.

Authorization: Bearer rgn_live_...

Memorizza le chiavi in una variabile d’ambiente o in un gestore di segreti. Non inserirle nel codice del browser, nei pacchetti di app mobili, nei repository pubblici o nei log. L’accesso da browser di altre origini non è abilitato: invia le richieste tramite il tuo server.

Le chiavi disabilitate, eliminate o scadute cessano subito di autenticare. Regunow conserva solo un hash del segreto e non può mostrarlo di nuovo. Crea una chiave sostitutiva quando serve.

L’accesso Pro e l’accettazione delle politiche vengono verificati a ogni richiesta. Se ricevi legal_acceptance_required, il titolare della chiave deve accedere e aprire Accettazione legale. Una chiave API non può accettare politiche.

GET/api/v1/models

Consulta modelli, livelli di impegno, giurisdizioni, lingue di risposta e funzionalità supportati. Questo endpoint autenticato non addebita crediti separatamente ed è utile per verificare una chiave prima di una richiesta di chat.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Usa i valori del catalogo del tuo ambiente. In modalità Giurisdizione, ometti model e effort per usare i valori predefiniti accettati. Se li specifichi, devono corrispondere a Sonnet 4.6 / Alto. Senza allegati, il servizio di recupero gestisce il modello di risposta; il campo del modello descrive la selezione validata.

POST/api/v1/chat/completions

Invia un corpo JSON contenente un array messages. Per impostazione predefinita, l’API restituisce la risposta completa in JSON. Imposta stream su true per ricevere il testo progressivamente.

{
  "messages": [{
    "role": "user",
    "content": "What retention period does this policy specify? Cite the document."
  }],
  "mode": "freestyle",
  "web_search": "off",
  "response_language": "en",
  "file_ids": ["YOUR_FILE_ID"]
}

Sostituisci YOUR_FILE_ID con l’UUID restituito da un caricamento riuscito. A ogni domanda successiva, invia la cronologia pertinente di utente e assistente e reinvia i file_ids desiderati. L’API non ricorda automaticamente cronologia e allegati.

I messaggi di sistema e i campi sconosciuti vengono rifiutati. L’API non espone generazione di immagini o report, ingresso audio né accesso alle memorie salvate. Le immagini caricate possono essere usate come input per le domande.

Una richiesta riuscita restituisce object: "regunow.chat.completion", risposta, metadati delle fonti, utilizzo e tempi. I valori seguenti sono illustrativi.

{
  "id": "request-uuid",
  "request_id": "request-uuid",
  "object": "regunow.chat.completion",
  "created": 1790812800,
  "model": "jp.anthropic.claude-sonnet-4-6",
  "latency": {
    "time_to_first_token_ms": 2345,
    "time_to_answer_completion_ms": 9876
  },
  "output": {
    "input_files": [],
    "role": "assistant",
    "content": "The complete answer...",
    "finish_reason": "end_turn",
    "citations": [],
    "sources": [],
    "web_search": false
  },
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 456,
    "charged_microcredits": 789000,
    "charged_credits": 0.789
  }
}

• output.content contiene il testo definitivo della risposta. Le posizioni delle citazioni si riferiscono a questa stringa finale; sourceIndexes identifica elementi in output.sources.
• Le fonti includono titolo, nome del file, tipo MIME, URI ed estratto recuperato. Mostra estratti e citazioni accanto alla risposta.
• Un URI di fonte indica una posizione, che può trovarsi in un archivio privato. Presenta come link accessibili solo gli URL pubblici degli editori. L’API non espone download o traduzione dei file sorgente normativi.
• Quando ci sono allegati, output.input_files identifica i file forniti. Le fonti degli allegati hanno un file_id; quelle normative e web hanno file_id: null. Gli URI degli allegati sono null.
• La presenza di un file di input non dimostra che sostenga ogni affermazione. I modelli possono omettere citazioni nel testo; immagini e scansioni possono avere estratti vuoti.

I conteggi dei token possono essere null se il servizio di recupero non li espone: significa sconosciuto, non zero. charged_credits è l’addebito registrato al cliente. created è un timestamp Unix in secondi; le latenze sono in millisecondi.

Ogni risposta degli endpoint contiene un’intestazione X-Request-Id. Conserva l’identificatore per la diagnosi. Anche il JSON delle risposte di chat e degli errori contiene request_id.

Imposta "stream": true. La risposta usa text/event-stream. Con cURL aggiungi -N per disabilitare il buffering dell’output.

curl --fail-with-body -N \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: streaming-question-001" \
  -d '{
    "messages": [{"role":"user","content":"Summarize EU product-safety obligations."}],
    "mode": "jurisdiction",
    "jurisdiction": "eu",
    "stream": true
  }'

Leggi eventi SSE completi separati da righe vuote; un blocco di rete può contenere parte di un evento o più eventi. Accoda choices[0].delta.content quando arriva. Ignora i commenti di mantenimento della connessione che iniziano con :.

data: {"choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"The answer begins..."},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"choices":[],"usage":{"prompt_tokens":1234,"completion_tokens":456,"total_tokens":1690},"regunow":{"output":{},"latency":{},"usage":{"charged_credits":0.789,"charged_microcredits":789000}}}

data: [DONE]

L’evento finale dei metadati ha un array choices vuoto. Leggi risposta definitiva, citazioni e fonti da regunow.output, tempi da regunow.latency e crediti da regunow.usage. I conteggi dei token usano usage.prompt_tokens e usage.completion_tokens.

Recupero e gestione delle citazioni possono causare pause. Considera il testo provvisorio fino ai metadati finali. Un errore dopo l’avvio dello streaming arriva come oggetto error seguito da [DONE]; HTTP 200 da solo non conferma il successo. Errori precedenti di autenticazione o validazione restituiscono normali risposte JSON.

La ripetizione di un’operazione completata resta SSE e restituisce la risposta salvata in un solo blocco di testo con X-Idempotent-Replayed: true.

Carica documenti o immagini, poi allega i loro ID a una richiesta di chat. Condividono Libreria e quota di archiviazione del titolare della chiave. I documenti possono arrivare a 10 MiB e le immagini a 5 MiB.

Caricamento diretto (consigliato)

Questo flusso in tre passaggi invia i byte originali direttamente all’archivio, evitando i limiti del corpo di richiesta dell’applicazione. Usalo per integrazioni ospitate, soprattutto con file grandi.

POST/api/v1/files/upload-intents

Invia solo name, mime_type e bytes (la dimensione esatta). Una richiesta riuscita restituisce HTTP 201 con l’ID di un file in attesa e un URL firmato valido per 300 secondi.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/upload-intents" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-intent-001" \
  -d '{"name":"policy.txt","mime_type":"text/plain","bytes":16384}'

{
  "id": "YOUR_FILE_ID",
  "status": "pending",
  "upload_method": "PUT",
  "upload_url": "SIGNED_UPLOAD_URL",
  "upload_headers": {"Content-Type": "text/plain"},
  "expires_in": 300
}

Imposta FILE_ID sull’id restituito. Usa upload_method, upload_url e upload_headers ricevuti per caricare esattamente i byte originali. Imposta la Content-Length esatta. Non inviare la chiave API Regunow all’URL di caricamento e non registrare gli URL firmati nei log.

# Set UPLOAD_URL from the intent response. Use its returned upload_headers.
# This example assumes policy.txt is exactly 16,384 bytes.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -H "Content-Length: 16384" \
  --data-binary @./policy.txt

POST/api/v1/files/{fileId}/complete

Invia {} con una chiave di idempotenza diversa. La finalizzazione valida i byte e restituisce HTTP 200 con un file disponibile. Il suo ID può essere usato in file_ids solo dopo il successo.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-complete-001" \
  -d '{}'

Se l’URL scade, elimina il file in attesa inutilizzato e prepara un nuovo caricamento con una nuova chiave. Ripetere la preparazione non prolunga la validità dell’URL. Se l’esito della finalizzazione è incerto, recupera prima lo stato del file. Se è ancora in attesa, riprova con una nuova chiave di idempotenza; quella precedente restituisce l’esito salvato. Finalizzare un file già disponibile restituisce i metadati.

Caricamento multipart

POST/api/v1/files

Per file piccoli, invia un campo multipart/form-data chiamato file. Invia i byte originali, non base64 o URL remoti. Il gateway di hosting può imporre un limite di corpo inferiore al limite dei file dell’API.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Idempotency-Key: policy-upload-001" \
  -F "file=@./policy.pdf;type=application/pdf"

Un caricamento riuscito restituisce HTTP 201 con un file disponibile; non serve una chiamata di finalizzazione separata.

{
  "id": "YOUR_FILE_ID",
  "object": "regunow.file",
  "name": "policy.pdf",
  "mime_type": "application/pdf",
  "category": "file",
  "bytes": 16384,
  "status": "available",
  "created_at": "2026-10-01T00:00:00Z",
  "request_id": "request-uuid",
  "usage": {"charged_microcredits":500,"charged_credits":0.0005}
}

Elencare, recuperare ed eliminare file

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files?limit=20" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Le chiavi dello stesso account accedono ai file disponibili nella sua Libreria. I file mancanti e quelli di altri account restituiscono entrambi 404. Se servi più utenti tramite un account, applica le tue autorizzazioni prima di allegare o eliminare file.

I caricamenti in attesa o non riusciti occupano quota finché la pulizia non termina correttamente. Quelli incompleti da oltre 24 ore possono essere ripuliti. Un file disponibile ha superato la validazione del caricamento; l’estrazione avviene alla domanda, quindi documenti corrotti, cifrati o illeggibili possono ancora fallire nell’analisi.

Richieste di chat, caricamenti ed eliminazioni registrano l’utilizzo misurato. Catalogo dei modelli e letture dei metadati non hanno addebiti separati in crediti. Estrazione dei documenti e analisi delle immagini sono addebitate nella richiesta di chat.

Leggi il costo di un’operazione in usage.charged_credits. Un credito equivale a 1.000.000 di microcrediti. I limiti delle chiavi sono separati dai crediti dell’account; entrambi possono bloccare una richiesta. Controlla l’utilizzo e imposta i limiti in Impostazioni → Chiavi API.

I limiti di contesto e visione del modello continuano ad applicarsi anche se ogni messaggio e allegato rispetta i limiti API. I budget delle chiavi si azzerano su periodi mobili giornalieri, settimanali o mensili, dalla creazione della chiave o dal rinnovo del periodo precedente.

Una richiesta avviata con budget disponibile può superare leggermente un piccolo saldo residuo, poiché il costo finale è noto dopo la generazione. Al raggiungimento del limite si fermano nuove richieste di chat e modifiche ai file. Le prenotazioni impediscono alle richieste simultanee di spendere lo stesso budget disponibile.

Invia un Idempotency-Key per ogni richiesta di chat, caricamento, finalizzazione ed eliminazione. È facoltativo, ma fortemente consigliato per evitare lavoro e addebiti duplicati dopo errori di connessione.

Idempotency-Key: a-unique-key-for-this-operation

• Genera una chiave univoca per ogni nuova operazione e salvala insieme alla richiesta originale.
• Riprova con la stessa chiave API, chiave di idempotenza e input invariati. Dopo la contabilizzazione, stato e risposta salvati possono essere riprodotti per 24 ore senza nuove chiamate al fornitore né addebiti.
• Una ripetizione include X-Idempotent-Replayed: true. Riutilizzare la chiave con input diversi o mentre la prima richiesta è in corso restituisce 409.
• Gli esiti in cache possono includere errori. La stessa chiave può restituire lo stesso errore invece di rieseguire. Controlla l’esito prima di una nuova operazione.
• Scaduta la finestra di ripetizione, riutilizzare una chiave avvia una nuova richiesta che può comportare un altro addebito.

Usa attese esponenziali per errori temporanei di rete, limiti di frequenza o servizio. Mantieni la chiave di idempotenza mentre risolvi una richiesta dall’esito incerto. Correggi prima input non validi, credenziali scadute o crediti esauriti.

Eliminare un file non cancella una risposta di chat o caricamento in cache durante la sua finestra di ripetizione. Ripetere un caricamento dopo l’eliminazione restituisce la risposta originale senza ricreare il file.

Gli errori usano una struttura JSON stabile. Controlla error.code per gestirli e conserva request_id o l’intestazione X-Request-Id per l’assistenza.

{
  "error": {
    "type": "request_error",
    "code": "invalid_request",
    "message": "messages must contain 1 to 20 alternating user/assistant messages, end with a user message, and stay within 64,000 characters."
  },
  "request_id": "request-uuid"
}