Developers

The Houston API.

Start and drive your Houston agents' missions from your own code. One API key, three ways in: a REST API, the Agent2Agent (A2A) protocol, and MCP. Give an agent an instruction, then poll, stream, or get a signed webhook when it finishes.

60-second quickstart REST reference

What the API does

Every Houston agent runs missions: you hand it an instruction in natural language, it does the work across your connected tools, and it returns a result. The API exposes that exact loop programmatically, so you can trigger agents from a cron job, a backend, another agent, or any tool that speaks MCP or A2A.

Authentication

The API authenticates with an API key. Mint one in the Houston app under Settings → API Keys. Keys look like hst_... and are shown only once at creation, so copy it somewhere safe immediately.

Send it as a bearer token on every request:

Authorization: Bearer hst_9f2c1a7b4e8d0364f1a2b3c4d5e6f7089f2c1a7b4e8d0364f1a2b3c4d5e6f708

Keep keys server-side

An API key can start missions and read their results. Treat it like a password: never ship it in a browser, mobile app, or public repository. You can revoke a key at any time from Settings → API Keys.

Base URL

All endpoints live on the Houston Cloud gateway:

https://poc-gateway.gethouston.ai

Every path below is relative to that origin. All requests and responses are JSON (application/json), except the streaming endpoints, which are Server-Sent Events.

Three surfaces

Pick the surface that fits how you are integrating. They all drive the same agents and the same missions underneath.

REST

Missions API

Plain HTTP + JSON. Create a mission, poll or stream it, cancel it, and receive signed webhooks. The most direct way in.

A2A

Agent2Agent

A standard JSON-RPC agent protocol. Point any A2A-capable agent (LangGraph, CrewAI, ADK) straight at your Houston agent.

MCP

Model Context Protocol

Expose your agents as tools to Claude Code and any MCP client over a single Streamable HTTP endpoint.

60-second quickstart

This uses the REST Missions API. Replace hst_... with your key and revenue-manager with your agent's slug.

1 · Start a mission

POST an instruction to the agent. You get a 202 Accepted back immediately with the mission id; the agent keeps working in the background.

POST /v1/agents/:slug/missions

curl -X POST https://poc-gateway.gethouston.ai/v1/agents/revenue-manager/missions \
  -H "Authorization: Bearer hst_9f2c1a7b4e8d0364f1a2b3c4d5e6f7089f2c1a7b4e8d0364f1a2b3c4d5e6f708" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Run a market pulse for Lisbon, check-in 2026-08-14 for 3 nights.",
    "mode": "auto",
    "webhook": {
      "url": "https://api.acme.com/hooks/houston",
      "secret": "whsec_a1b2c3d4e5f6"
    }
  }'

202 Accepted

{
  "id": "msn_7Q4c1a9f2b",
  "agentSlug": "revenue-manager",
  "conversationId": "cnv_3e8d0364f1",
  "status": "running",
  "createdAt": "2026-07-12T09:31:07.482Z"
}

2 · Get the result

You have three ways to learn how the mission ends. Use whichever fits your stack:

Poll the mission until status becomes terminal (completed, failed, or canceled). The result field carries the agent's final text.
Stream live progress over Server-Sent Events, with Last-Event-ID resume.
Webhook — the simplest for servers. Houston POSTs a signed payload to your URL the moment the mission finishes. No polling.

Poll:

GET /v1/agents/:slug/missions/:id

curl https://poc-gateway.gethouston.ai/v1/agents/revenue-manager/missions/msn_7Q4c1a9f2b \
  -H "Authorization: Bearer hst_9f2c1a7b4e8d0364f1a2b3c4d5e6f7089f2c1a7b4e8d0364f1a2b3c4d5e6f708"

{
  "id": "msn_7Q4c1a9f2b",
  "agentSlug": "revenue-manager",
  "conversationId": "cnv_3e8d0364f1",
  "status": "completed",
  "result": "Market pulse for Lisbon (Aug 14-17) is ready...",
  "createdAt": "2026-07-12T09:31:07.482Z"
}

Or stream with Server-Sent Events:

GET /v1/agents/:slug/missions/:id/events

curl -N https://poc-gateway.gethouston.ai/v1/agents/revenue-manager/missions/msn_7Q4c1a9f2b/events \
  -H "Authorization: Bearer hst_9f2c1a7b4e8d0364f1a2b3c4d5e6f7089f2c1a7b4e8d0364f1a2b3c4d5e6f708"

Streaming in the browser

EventSource cannot set headers, so the events endpoint also accepts the key as a query parameter: ?token=hst_.... Reconnect from where you left off by sending the Last-Event-ID header (curl and native SSE clients do this automatically).

3 · Find your agents

Do not know an agent's slug? List everything the key can reach:

GET /agents

curl https://poc-gateway.gethouston.ai/agents \
  -H "Authorization: Bearer hst_9f2c1a7b4e8d0364f1a2b3c4d5e6f7089f2c1a7b4e8d0364f1a2b3c4d5e6f708"

That's the whole loop

Create → poll, stream, or await a webhook → read the result. The Missions reference documents every field, webhook signing, cancellation, and key scoping in full.