Ir para o conteúdo

API e MCP

Construa com o Piqline

As ferramentas e os agentes do seu workspace, via HTTP ou MCP. Uma chave, scopes, erros legíveis.

  • 92 ferramentas
  • 6 agentes
  • 5 scopes
  • REST e MCP

Sua primeira chamada

curl -s https://piqline.com/api/v1/workspace \
  -H "Authorization: Bearer $PIQLINE_API_KEY"
Resposta
{
  "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 onde começar

A API do Piqline dá aos seus scripts e agentes acesso ao seu workspace: as mesmas ferramentas e os mesmos agentes do assistente do painel, via HTTP ou MCP (Model Context Protocol). Cada chamada age em um workspace, com os direitos do membro que criou a chave.

O que você precisa#

  • Um workspace Piqline em que você seja owner ou admin. Os membros veem a página de chaves somente para leitura.
  • Uma ferramenta que envie requisições HTTP (curl nos exemplos) ou um cliente MCP.

1. Criar uma chave#

  1. Abra Configurações → API e MCP.
  2. Dê um nome à chave, marque seus scopes (comece com read) e escolha uma validade.
  3. Clique em Criar chave e copie a chave. Ela é exibida uma única vez.

Guarde-a em uma variável de ambiente:

Shell
export PIQLINE_API_KEY="piq_live_…"

2. Verificar a chave#

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

Resposta:

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 lista o que a chave pode fazer, e limits o que ainda resta. Um 401 indica que a chave está ausente, foi copiada errado ou foi revogada: veja Erros.

3. Chamar uma ferramenta#

Uma ferramenta é uma capacidade do assistente: ler o corpus, buscar ao vivo, escrever, agir. Este exemplo lê os volumes de coleta dos últimos 7 dias:

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

A resposta traz o nome da ferramenta e sua saída (abreviada aqui):

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

As 92 ferramentas chamáveis, seus scopes e suas entradas estão listados no catálogo.

4. Consultar um agente#

Um agente encadeia várias ferramentas e responde em linguagem natural. A chave precisa do scope agents, além dos scopes das ferramentas que o agente pode 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 ?"}'

Resposta, abreviada:

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

Mais detalhes em Agentes.

5. Conectar um cliente MCP#

Com o Claude Code:

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

Os outros clientes estão em Servidor MCP.

Ainda não disponível#

  • Webhooks. Nada é enviado aos seus sistemas. Para acompanhar o que chega, consulte getSignals ou searchItems em intervalos regulares.
  • SDKs oficiais. O documento OpenAPI descreve todas as rotas: um gerador de clientes o transforma em um SDK na sua linguagem.
  • Login por OAuth. Apenas chaves são aceitas. Os conectores que exigem OAuth, como os do claude.ai e do ChatGPT, ainda não conseguem se conectar.
  • Exportação em massa. As ferramentas devolvem páginas de resultados limitadas (no máximo 40 itens para searchItems).

Uma dúvida sobre a API, ou um erro nesta página? Escreva para nós.