OpenQCoreAI
Inizia

Resources · Knowledge API

Knowledge API Documentation

Comprehensive reference for workspace knowledge ingestion, retrieval, ask workflows, and production-safe constraints.

Torna alla documentazioneVai agli endpoint

Endpoint

GET /api/v1/console/knowledge
POST /api/v1/console/knowledge
POST /api/v1/console/knowledge/upload
GET /api/v1/console/knowledge/{item_id}
PATCH /api/v1/console/knowledge/{item_id}
DELETE /api/v1/console/knowledge/{item_id}
POST /api/v1/console/knowledge/ask

Header richiesti

Authorization: Bearer [token] o autenticazione con chiave APIX-Scope-Type: workspaceX-Workspace-ID: [workspace_uuid]Content-Type: application/json (o multipart/form-data per il caricamento)

Esempio di caricamento

bash
curl -X POST "/api/v1/console/knowledge/upload" \
  -H "Authorization: Bearer [token]" \
  -H "X-Scope-Type: workspace" \
  -H "X-Workspace-ID: [workspace_uuid]" \
  -F "file=@handbook.pdf" \
  -F "title=Team Handbook" \
  -F "tags=hr,policy"

Esempio di richiesta

json
{
  "question": "What is our remote-work policy?",
  "top_k": 5,
  "filters": {
    "tags": ["hr", "policy"]
  },
  "session_id": "sess_123"
}

Esempio di risposta

json
{
  "success": true,
  "answer": "Employees may work remotely up to 3 days per week...",
  "citations": [
    {
      "item_id": "kb_456",
      "title": "Team Handbook",
      "score": 0.91
    }
  ],
  "usage": {
    "input_tokens": 180,
    "output_tokens": 72
  },
  "metadata": {
    "retrieved_items": 5
  }
}

Vincoli della knowledge

  • Dimensione massima file: 20MB per caricamento.
  • Formati supportati: PDF, DOC, DOCX, TXT, Markdown.
  • L'ingestione viene eseguita in modo asincrono da worker in background.
  • È richiesto lo scope workspace per le operazioni della console knowledge.

Ciclo di vita dell'ingestione

  1. pending: file accettato e messo in coda.
  2. processing: estrazione/chunking/embedding in corso.
  3. processed: l'elemento è indicizzato e pronto per le query.
  4. failed: l'ingestione è fallita con metadati diagnostici.

Modelli di errore

400

Payload non valido o filtri malformati.

401

Autenticazione mancante o non valida.

403

Accesso all'area di lavoro negato per ruolo/ambito.

404

Elemento di conoscenza non trovato.

413

Il file caricato supera la dimensione consentita.

415

Tipo di contenuto del file non supportato.

422

Validazione fallita nello schema/contesto della richiesta.

429

Limite di richieste superato.