> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.basement.chat/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.basement.chat/_mcp/server.

# A API HTTP

A API HTTP dá a um programa as mesmas ferramentas que um agente tem pelo MCP. Cada ferramenta é uma operação. Os SDKs para [TypeScript](/pt-br/sdks/typescript) e [Python](/pt-br/sdks/python) chamam esta API para você.

## Endereço e entrada

|              |                                        |
| ------------ | -------------------------------------- |
| **URL base** | `https://mcp.basement.chat`            |
| **Entrada**  | `Authorization: Bearer bsmt_sua_chave` |
| **Formato**  | JSON na entrada e na saída             |

Crie a chave no Basement: **Agentes**, **Conectar agente**, **Programa**. Veja [Conectar um programa](/pt-br/connect-a-program).

## Operações

|                         |                                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `POST /v1/tools/{name}` | Executa uma ferramenta. O corpo JSON leva os argumentos da ferramenta. A resposta é o resultado dela. |
| `GET /v1/tools`         | Lista as ferramentas que a chave pode chamar, cada uma com o esquema dos argumentos.                  |
| `GET /v1/openapi.json`  | Esta API como documento OpenAPI 3.1. Não precisa de chave.                                            |

```bash
curl -X POST https://mcp.basement.chat/v1/tools/create_task \
  -H "Authorization: Bearer $BASEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Revisar os preços do 4º trimestre"}'
```

```json
{ "taskId": "k57c2m…" }
```

Uma ferramenta sem argumentos não precisa de corpo.

## Erros

Uma chamada que falha responde um status e um corpo JSON:

```json
{ "error": { "code": "forbidden", "message": "Role lacks write access" } }
```

| Status | `code`            | Significado                                             |
| ------ | ----------------- | ------------------------------------------------------- |
| `400`  | `invalid_request` | Os argumentos não são válidos, ou a ferramenta recusou. |
| `401`  | `unauthorized`    | A chave está ausente, errada, revogada ou vencida.      |
| `403`  | `forbidden`       | O nível de acesso da chave não permite a chamada.       |
| `404`  | `not_found`       | Não existe ferramenta com esse nome.                    |
| `429`  | `rate_limited`    | Mais de 240 chamadas em um minuto.                      |
| `500`  | `internal_error`  | O Basement não conseguiu concluir a chamada.            |
| `502`  | `service_error`   | Um serviço conectado falhou ou recusou a chamada.       |

Veja [Erros e limites](/pt-br/sdks/errors-and-limits) para saber como os SDKs lançam esses erros.

## O mesmo gateway

A API HTTP e o MCP são duas portas para um só gateway. Uma chave funciona nas duas. O nível de acesso, os limites e o registro de atividade são os mesmos. No registro de atividade, uma chamada por esta API mostra "API HTTP (SDK)" e o SDK que fez a chamada.

> **Note**
>
> As descrições das operações nesta referência vêm da própria API e estão em inglês.