Ferramentas — API

Veja o guia conceitual em Ferramentas.

Registrar

`POST /api/v1/tools` admin

Requisição

{
  "name": "consultar_fatura",
  "description": "Consulta os detalhes de uma fatura pelo ID. Retorna valor, status e vencimento.",
  "endpoint_url": "https://api.financeiro.exemplo.com/faturas/{id}",
  "http_method": "GET",
  "auth_type": "api_key",
  "auth_config": { "header": "X-API-Key", "value": "sua-chave" },
  "input_schema": {
    "type": "object",
    "properties": { "id": { "type": "string", "description": "ID da fatura" } },
    "required": ["id"]
  }
}

auth_type: none · api_key · bearer · oauth2_client_credentials · spiffe (identidade de workload).

Resposta 201 — a ferramenta criada.

Listar e obter

Endpoint	Papel	Descrição
`GET /api/v1/tools`	leitor	Lista as ferramentas ativas.
`GET /api/v1/tools/{tool_id}`	leitor	Detalha uma ferramenta.

Atualizar e desativar

Endpoint	Papel	Descrição
`PUT /api/v1/tools/{tool_id}`	admin	Atualização parcial.
`DELETE /api/v1/tools/{tool_id}`	admin	Desativa (soft delete): concessões são preservadas, mas a execução é bloqueada. Resposta `204`.

Importar

`POST /api/v1/tools/import/postman` admin

`POST /api/v1/tools/import/openapi` admin

Importa ferramentas de uma Collection Postman v2.1 ou de uma spec OpenAPI 3.x.

Parâmetros de query: ?dry_run=true (apenas pré-visualiza) · ?overwrite=true (sobrescreve existentes).

Resposta 200

{
  "imported": [{ "name": "consultar_fatura", "id": 5 }],
  "skipped":  [{ "name": "criar_fatura", "reason": "já existe" }],
  "errors":   [{ "name": "excluir_registro", "reason": "descrição ausente" }]
}

Registrar​

POST /api/v1/tools admin​

Listar e obter​

Atualizar e desativar​

Importar​

POST /api/v1/tools/import/postman admin​

POST /api/v1/tools/import/openapi admin​