Vai al contenuto

API e MCP

Costruisci su Piqline

I tool e gli agenti del tuo workspace, via HTTP o MCP. Una chiave, scope, errori leggibili.

  • 92 tool
  • 6 agenti
  • 5 scope
  • REST e MCP

La tua prima chiamata

curl -s https://piqline.com/api/v1/workspace \
  -H "Authorization: Bearer $PIQLINE_API_KEY"
Risposta
{
  "workspace": { "id": "b7a1c3e0-5d2f-4c8a-9e41-2f6d0a7b1c93", "name": "Atelier" },
  "key": { "name": "Claude Code", "prefix": "piq_live_Ab12Cd", "scopes": ["read", "agents"] },
  "limits": { "requests_per_minute": 120, "requests_today": 1 }
}

Da dove iniziare

L'API di Piqline dà ai tuoi script e ai tuoi agenti accesso al tuo workspace: gli stessi tool e gli stessi agenti dell'assistente della dashboard, via HTTP o MCP (Model Context Protocol). Ogni chiamata agisce su un workspace, con i diritti del membro che ha creato la chiave.

Che cosa ti serve#

  • Un workspace Piqline in cui sei owner o admin. I membri vedono la pagina delle chiavi in sola lettura.
  • Uno strumento che invia richieste HTTP (negli esempi curl) oppure un client MCP.

1. Crea una chiave#

  1. Apri Impostazioni → API e MCP.
  2. Dai un nome alla chiave, seleziona i suoi scope (inizia con read) e scegli una scadenza.
  3. Clicca su Crea chiave, poi copia la chiave. Viene mostrata una sola volta.

Salvala in una variabile d'ambiente:

Shell
export PIQLINE_API_KEY="piq_live_…"

2. Verifica la chiave#

curl -s https://piqline.com/api/v1/workspace \
  -H "Authorization: Bearer $PIQLINE_API_KEY"

Risposta:

JSON
{
  "workspace": { "id": "b7a1c3e0-5d2f-4c8a-9e41-2f6d0a7b1c93", "name": "Atelier" },
  "key": {
    "id": "0d4e8f2a-71c6-4b3d-8a55-c9e2b6f10d47",
    "name": "Claude Code",
    "prefix": "piq_live_Ab12Cd",
    "scopes": ["read", "agents"]
  },
  "acting_as": {
    "user_id": "3c9a52e1-8b47-4d06-a2f3-71e0b5d4c689",
    "email": "vous@exemple.fr",
    "role": "owner"
  },
  "limits": {
    "requests_per_minute": 120,
    "agent_runs_per_minute": 10,
    "requests_per_day": 20000,
    "requests_today": 1
  }
}

key.scopes elenca ciò che la chiave può fare, e limits ciò che le resta. Un 401 indica che la chiave manca, è stata copiata male o è stata revocata: vedi Errori.

3. Chiama un tool#

Un tool è una capacità dell'assistente: leggere il corpus, cercare in diretta, scrivere, agire. Questo esempio legge i volumi di raccolta degli ultimi 7 giorni:

curl -s https://piqline.com/api/v1/tools/getCoverageStats \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"7d"}'

La risposta contiene il nome del tool e il suo output (abbreviato qui):

JSON
{
  "tool": "getCoverageStats",
  "output": {
    "period": "7d",
    "itemsTotal": 1842,
    "itemsPeriod": 214,
    "items24h": 37,
    "sources": 12,
    "byPlatform": [{ "platform": "rss", "items": 904, "items24h": 20 }]
  }
}

I 92 tool richiamabili, i loro scope e i loro input sono elencati nel catalogo.

4. Interroga un agente#

Un agente concatena più tool e risponde in linguaggio naturale. La chiave richiede lo scope agents, più gli scope dei tool che l'agente può usare.

curl -s https://piqline.com/api/v1/agents/piqline \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Combien de sources suit ce workspace, et lesquelles sont en erreur ?"}'

Risposta, abbreviata:

JSON
{
  "agent": "piqline",
  "status": "completed",
  "text": "Le workspace suit 12 sources, dont 2 en erreur : …",
  "tool_calls": [{ "tool": "listSources", "state": "output-available" }],
  "pending": []
}

Altri dettagli in Agenti.

5. Collega un client MCP#

Con Claude Code:

Shell
claude mcp add --transport http piqline https://piqline.com/api/mcp \
  --header "Authorization: Bearer $PIQLINE_API_KEY"

Gli altri client sono trattati in Server MCP.

Non ancora disponibile#

  • Webhook. Nulla viene inviato ai tuoi sistemi. Per seguire ciò che arriva, interroga getSignals o searchItems a intervalli regolari.
  • SDK ufficiali. Il documento OpenAPI descrive ogni route: un generatore di client lo trasforma in un SDK nel tuo linguaggio.
  • Accesso OAuth. Sono accettate solo le chiavi. I connettori che richiedono OAuth, come quelli di claude.ai e ChatGPT, non possono ancora collegarsi.
  • Esportazione in blocco. I tool restituiscono pagine di risultati limitate (al massimo 40 elementi per searchItems).

Una domanda sull'API, o un errore in questa pagina? Scrivici.