Skip to navigation
Overview

The HTTP API

The Gateway over plain HTTP, for programs.
View as Markdown

The HTTP API gives a program the same tools that an agent has through MCP. Each tool is one operation. The SDKs for TypeScript and Python call this API for you.

Address and sign in

Base URLhttps://mcp.basement.chat
Sign inAuthorization: Bearer bsmt_your_key
FormatJSON in, JSON out

Create the key in Basement: Agents, Connect agent, Program. See 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/toolsLists the tools the key can call, each with the schema of its arguments.
GET /v1/openapi.jsonThis API as an OpenAPI 3.1 document. It needs no key.
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"}'
{ "taskId": "k57c2m…" }

A tool that takes no arguments needs no body.

Errors

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

{ "error": { "code": "forbidden", "message": "Role lacks write access" } }
StatuscodeMeaning
400invalid_requestThe arguments are not valid, or the tool refused them.
401unauthorizedThe key is missing, wrong, revoked or expired.
403forbiddenThe key’s access level does not allow the call.
404not_foundThere is no tool with this name.
429rate_limitedMore than 240 calls in a minute.
500internal_errorBasement failed to complete the call.
502service_errorA connected service failed or refused the call.

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