La API de Piqline da a tus scripts y agentes acceso a tu workspace: las mismas herramientas y los mismos agentes que el asistente del panel, por HTTP o por MCP (Model Context Protocol). Cada llamada actúa sobre un workspace, con los permisos del miembro que creó la clave.
Qué necesitas#
- Un workspace de Piqline del que seas propietario (owner) o administrador (admin). Los miembros ven la página de claves en solo lectura.
- Una herramienta que envíe peticiones HTTP (
curlen los ejemplos) o un cliente MCP.
1. Crear una clave#
- Abre Ajustes → API y MCP.
- Ponle un nombre a la clave, marca sus scopes (empieza con
read) y elige una caducidad. - Haz clic en Crear clave y copia la clave. Solo se muestra una vez.
Guárdala en una variable de entorno:
export PIQLINE_API_KEY="piq_live_…"2. Verificar la clave#
curl -s https://piqline.com/api/v1/workspace \
-H "Authorization: Bearer $PIQLINE_API_KEY"const response = await fetch("https://piqline.com/api/v1/workspace", {
headers: { Authorization: "Bearer " + process.env.PIQLINE_API_KEY },
});
const data = await response.json();import os
import requests
response = requests.get(
"https://piqline.com/api/v1/workspace",
headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
)
data = response.json()Respuesta:
{
"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 indica lo que la clave puede hacer, y limits lo que le queda. Un 401 significa que la clave falta, está mal copiada o fue revocada: consulta Errores.
3. Llamar a una herramienta#
Una herramienta es una capacidad del asistente: leer el corpus, buscar en directo, escribir, actuar. Este ejemplo lee los volúmenes de recogida de los últimos 7 días:
curl -s https://piqline.com/api/v1/tools/getCoverageStats \
-H "Authorization: Bearer $PIQLINE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period":"7d"}'const response = await fetch("https://piqline.com/api/v1/tools/getCoverageStats", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ period: "7d" }),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://piqline.com/api/v1/tools/getCoverageStats",
headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
json={"period": "7d"},
)
data = response.json()La respuesta incluye el nombre de la herramienta y su salida (abreviada aquí):
{
"tool": "getCoverageStats",
"output": {
"period": "7d",
"itemsTotal": 1842,
"itemsPeriod": 214,
"items24h": 37,
"sources": 12,
"byPlatform": [{ "platform": "rss", "items": 904, "items24h": 20 }]
}
}Las 92 herramientas invocables, sus scopes y sus entradas están en el catálogo.
4. Consultar a un agente#
Un agente encadena varias herramientas y responde en lenguaje natural. La clave necesita el scope agents, además de los scopes de las herramientas que el agente pueda usar.
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 ?"}'const response = await fetch("https://piqline.com/api/v1/agents/piqline", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ input: "Combien de sources suit ce workspace, et lesquelles sont en erreur ?" }),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://piqline.com/api/v1/agents/piqline",
headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
json={"input": "Combien de sources suit ce workspace, et lesquelles sont en erreur ?"},
)
data = response.json()Respuesta, abreviada:
{
"agent": "piqline",
"status": "completed",
"text": "Le workspace suit 12 sources, dont 2 en erreur : …",
"tool_calls": [{ "tool": "listSources", "state": "output-available" }],
"pending": []
}Más detalles en Agentes.
5. Conectar un cliente MCP#
Con Claude Code:
claude mcp add --transport http piqline https://piqline.com/api/mcp \
--header "Authorization: Bearer $PIQLINE_API_KEY"Los demás clientes se tratan en Servidor MCP.
Aún no disponible#
- Webhooks. No se envía nada a tus sistemas. Para seguir lo que entra, consulta
getSignalsosearchItemsa intervalos regulares. - SDK oficiales. El documento OpenAPI describe todas las rutas: un generador de clientes lo convierte en un SDK en tu lenguaje.
- Inicio de sesión con OAuth. Solo se aceptan claves. Los conectores que exigen OAuth, como los de claude.ai y ChatGPT, todavía no pueden conectarse.
- Exportación masiva. Las herramientas devuelven páginas de resultados acotadas (40 elementos como máximo en
searchItems).