# Inicio rápido

> De la clave a la primera llamada: crea una clave y consulta una herramienta, un agente o un cliente MCP.

Source: https://piqline.com/es/docs/api

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](/settings/api).
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.

> **Advertencia.** La clave actúa con tus permisos sobre el workspace. Guárdala en un gestor de secretos o en una variable de entorno, nunca en el código ni en un repositorio. Si se filtra, revócala desde la misma página.

Guárdala en una variable de entorno:

```bash
export PIQLINE_API_KEY="piq_live_…"
```

## 2. Verificar la clave

```bash tab="curl"
curl -s https://piqline.com/api/v1/workspace \
  -H "Authorization: Bearer $PIQLINE_API_KEY"
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/workspace", {
  headers: { Authorization: "Bearer " + process.env.PIQLINE_API_KEY },
});
const data = await response.json();
```
```python tab="Python"
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:

```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](/es/docs/api/errors).

## 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:

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/getCoverageStats \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"7d"}'
```
```javascript tab="JavaScript"
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();
```
```python tab="Python"
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í):

```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](/es/docs/api/tools#catalogo).

## 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.

```bash tab="curl"
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 ?"}'
```
```javascript tab="JavaScript"
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();
```
```python tab="Python"
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:

```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](/es/docs/api/agents).

## 5. Conectar un cliente MCP

Con Claude Code:

```bash
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](/es/docs/api/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](https://piqline.com/api/v1/openapi.json) 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`).
