Saltar al contenido

API y MCP

Construye sobre Piqline

Las herramientas y los agentes de tu workspace, por HTTP o por MCP. Una clave, scopes, errores legibles.

  • 92 herramientas
  • 6 agentes
  • 5 scopes
  • REST y MCP

Tu primera llamada

curl -s https://piqline.com/api/v1/workspace \
  -H "Authorization: Bearer $PIQLINE_API_KEY"
Respuesta
{
  "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 }
}

Por dónde empezar

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 (curl en los ejemplos) o un cliente MCP.

1. Crear una clave#

  1. Abre Ajustes → API y MCP.
  2. Ponle un nombre a la clave, marca sus scopes (empieza con read) y elige una caducidad.
  3. Haz clic en Crear clave y copia la clave. Solo se muestra una vez.

Guárdala en una variable de entorno:

Shell
export PIQLINE_API_KEY="piq_live_…"

2. Verificar la clave#

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

Respuesta:

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 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"}'

La respuesta incluye el nombre de la herramienta y su salida (abreviada aquí):

JSON
{
  "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 ?"}'

Respuesta, abreviada:

JSON
{
  "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:

Shell
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 getSignals o searchItems a 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).

¿Tienes una pregunta sobre la API o has encontrado un error en esta página? Escríbenos.