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

# The HTTP API

The HTTP API gives a program the same tools that an agent has through MCP. Each tool is one operation. The SDKs for [TypeScript](/sdks/typescript) and [Python](/sdks/python) call this API for you.

## Address and sign in

|              |                                       |
| ------------ | ------------------------------------- |
| **Base URL** | `https://mcp.basement.chat`           |
| **Sign in**  | `Authorization: Bearer bsmt_your_key` |
| **Format**   | JSON in, JSON out                     |

Create the key in Basement: **Agents**, **Connect agent**, **Program**. See [Connect a program](/connect-a-program).

## Operations

|                         |                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `POST /v1/tools/{name}` | Runs a tool. The JSON body holds the tool's arguments. The answer is the tool's result. |
| `GET /v1/tools`         | Lists the tools the key can call, each with the schema of its arguments.                |
| `GET /v1/openapi.json`  | This API as an OpenAPI 3.1 document. It needs no key.                                   |

```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": "Review the Q4 pricing"}'
```

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

A tool that takes no arguments needs no body.

## Errors

A call that fails answers a status and a JSON body:

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

| Status | `code`            | Meaning                                                |
| ------ | ----------------- | ------------------------------------------------------ |
| `400`  | `invalid_request` | The arguments are not valid, or the tool refused them. |
| `401`  | `unauthorized`    | The key is missing, wrong, revoked or expired.         |
| `403`  | `forbidden`       | The key's access level does not allow the call.        |
| `404`  | `not_found`       | There is no tool with this name.                       |
| `429`  | `rate_limited`    | More than 240 calls in a minute.                       |
| `500`  | `internal_error`  | Basement failed to complete the call.                  |
| `502`  | `service_error`   | A connected service failed or refused the call.        |

See [Errors and limits](/sdks/errors-and-limits) for how the SDKs raise these.

## The same gateway

The HTTP API and MCP are two doors to one gateway. A key works on both. The access level, the limits and the activity log are the same. In the activity log, a call through this API shows "HTTP API (SDK)" and the SDK that made it.