Getting Started con le API

Guida introduttiva per utilizzare le API di Emblema.

🔑 Autenticazione

Tutte le API di Emblema richiedono autenticazione. Supportiamo due metodi:

JWT Bearer Token

curl -X GET https://api.emblema.ai/v1/documents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

API Key

curl -X GET https://api.emblema.ai/v1/documents \
  -H "X-API-Key: YOUR_API_KEY"

🌐 Base URL

Production: https://api.emblema.ai
Staging: https://staging-api.emblema.ai
Development: http://localhost:3000/api

📚 API Disponibili

REST API

Endpoint principali:

• /api/v1/documents - Gestione documenti
• /api/v1/chat - Conversazioni AI
• /api/v1/search - Ricerca semantica
• /api/v1/knowledge-bases - Knowledge bases
• /api/v1/users - Gestione utenti

GraphQL API

Endpoint: /graphql

query GetDocuments {
  documents(limit: 10) {
    id
    name
    createdAt
    chunks {
      id
      text
    }
  }
}

🚀 Quick Start

1. Ottieni le Credenziali

# Login per ottenere JWT
curl -X POST https://api.emblema.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 3600
}

2. Prima Chiamata API

# Lista documenti
curl -X GET https://api.emblema.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN"

3. Upload Documento

# Upload file
curl -X POST https://api.emblema.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "name=My Document"

💬 Esempio Chat API

Inizia Conversazione

const response = await fetch(
  "https://api.emblema.ai/api/v1/chat/conversations",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Nuova conversazione",
      model: "gpt-4",
    }),
  },
);

const conversation = await response.json();

Invia Messaggio

const messageResponse = await fetch(
  `https://api.emblema.ai/api/v1/chat/conversations/${conversationId}/messages`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: "Qual è il contenuto del documento X?",
      stream: true,
    }),
  },
);

// Handle streaming response
const reader = messageResponse.body.getReader();

🔍 Ricerca Semantica

import requests

# Ricerca nei documenti
response = requests.post(
    'https://api.emblema.ai/api/v1/search',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'query': 'contratti con clausole di rinnovo automatico',
        'limit': 10,
        'filters': {
            'document_type': ['contract'],
            'date_range': {
                'from': '2024-01-01',
                'to': '2024-12-31'
            }
        }
    }
)

results = response.json()

📄 Response Format

Tutte le API seguono un formato standard:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  }
}

🔄 Rate Limiting

• Standard: 1000 richieste/ora
• Pro: 10000 richieste/ora
• Enterprise: Custom

Headers di risposta:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642521600

🔐 Best Practices

1. Usa HTTPS sempre in produzione
2. Ruota le API keys regolarmente
3. Gestisci i token in modo sicuro
4. Implementa retry logic per errori temporanei
5. Usa pagination per dataset grandi

📖 SDK Disponibili

JavaScript/TypeScript

npm install @emblema/sdk

import { EmblemaClient } from "@emblema/sdk";

const client = new EmblemaClient({
  apiKey: "YOUR_API_KEY",
});

const documents = await client.documents.list();

Python

pip install emblema-sdk

from emblema import EmblemaClient

client = EmblemaClient(api_key='YOUR_API_KEY')
documents = client.documents.list()

🆘 Supporto

• 📧 Email: api-support@emblema.ai
• 📖 API Reference Completa
• 💬 Community Discord

---

Pronto per iniziare? Esplora la documentazione completa delle API per tutti i dettagli! 🚀