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 webhook when it finishes.

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. Create one in the Houston app under Settings → API keys. The section is in the Houston desktop app, and in the web app when you are signed in to Houston cloud. Keys look like hst_... and are shown only once at creation, so copy yours somewhere safe right away.

Send it as a bearer token on every request:

Authorization: Bearer hst_9f2c1a7b4e8d0364f1a2b3c4d5e6f7089f2c1a7b4e8d0364f1a2b3c4d5e6f708

Keys are created and revoked in the app only. A key cannot list, create, or revoke keys: the /v1/keys routes refuse it with 403, like every route outside the public API (see API-key scope).

Organizations

Every person has a personal organization, the one the Houston app lists as Personal in its space menu, and can also belong to team organizations. A key belongs to you, not to an organization. It works in every organization you are a member of, and acts in one organization per request:

• No header: the request acts in your personal organization.
• x-houston-org: <organization id>: the request acts in that organization, for example a team organization you belong to. Send the header on every request. The events stream also accepts ?org=<organization id> for clients that cannot set headers. If a stream request carries both, ?org= wins.

Find the Organization ID in the Houston app under Settings → API keys, or in an AI Employee's Settings → API access. Both show the ID of the organization that is open in the app, with a copy button, so open the organization you want first. An organization ID is 16 hex characters, like 8c41e7a0d39b2f16. If you name an organization you are not a member of, the gateway answers 403:

{ "error": "not a member", "code": "not_member" }

Agents, missions, and A2A addresses all belong to one organization. A mission started in a team organization is only visible to requests that act in that same organization.

Base URL

All endpoints live on the Houston Cloud gateway:

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.

60-second quickstart

This uses the REST Missions API. Replace hst_... with your key and 3f9a1c07b2e84d65 with your agent's slug. A slug is the agent's id from GET /agents (step 3), 16 hex characters. To act in a team organization, add the x-houston-org header from Organizations.

1 · Start a mission

POST an instruction to the agent. You get a 202 Accepted back with the mission id, and the agent keeps working in the background. Mission and conversation ids are 32 hex characters.

curl -X POST https://gateway.gethouston.ai/v1/agents/3f9a1c07b2e84d65/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": "a7f3c91e0b2d4856e19c3f70b4a2d8e5",
  "agentSlug": "3f9a1c07b2e84d65",
  "conversationId": "5d0e8b3a6c1f4927b8e2a4c6d9f01b37",
  "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, and resume with Last-Event-ID or ?after=<id>.
• Webhook, the simplest for servers. Houston POSTs a payload to your URL when the mission finishes, signed if you set a secret. No polling.

Poll:

curl https://gateway.gethouston.ai/v1/agents/3f9a1c07b2e84d65/missions/a7f3c91e0b2d4856e19c3f70b4a2d8e5 \
  -H "Authorization: Bearer hst_9f2c1a7b4e8d0364f1a2b3c4d5e6f7089f2c1a7b4e8d0364f1a2b3c4d5e6f708"

{
  "id": "a7f3c91e0b2d4856e19c3f70b4a2d8e5",
  "agentSlug": "3f9a1c07b2e84d65",
  "conversationId": "5d0e8b3a6c1f4927b8e2a4c6d9f01b37",
  "status": "completed",
  "result": "Market pulse for Lisbon (Aug 14-17) is ready...",
  "createdAt": "2026-07-12T09:31:07.482Z",
  "completedAt": "2026-07-12T09:34:51.903Z"
}

Or stream with Server-Sent Events:

curl -N https://gateway.gethouston.ai/v1/agents/3f9a1c07b2e84d65/missions/a7f3c91e0b2d4856e19c3f70b4a2d8e5/events \
  -H "Authorization: Bearer hst_9f2c1a7b4e8d0364f1a2b3c4d5e6f7089f2c1a7b4e8d0364f1a2b3c4d5e6f708"

3 · Find your agents

Do not know an agent's slug? List the agents in the organization the request acts in:

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

The response is a JSON array. Each agent's id is its slug:

[
  {
    "id": "3f9a1c07b2e84d65",
    "name": "Revenue Manager",
    "createdAt": 1780401067482,
    ...
  }
]

createdAt is milliseconds since the Unix epoch. Items also carry fields the Houston app uses, such as workspaceId, role, assigned, and access; you only need id. In a team organization, members other than the owner see only the agents assigned to them.