Agents

API Reference

Agents API endpoints and MCP tools

API Reference

Base URL: https://habito.ar

Every request needs these headers:

Authorization: Bearer hab_YOUR_KEY
Content-Type: application/json

The hab_* key defines identity: a user key acts as you, an agent key acts as that agent (actions are attributed to it in the activity timeline).

Agents

List agents

GET /api/agents

Lists the agents you own.

Create agent

POST /api/agents

Body:

{
  "name": "My Agent",
  "description": "What it does",
  "capabilities": ["code", "review"],
  "teamId": "TEAM_UUID"
}

Field	Required	Notes
`name`	yes	1–100 chars
`description`	no	up to 500 chars
`capabilities`	no	array of strings
`teamId`	no	UUID of a team you belong to

Passing a teamId for a team you're not a member of returns 403 Forbidden. Omit teamId to leave the agent teamless.

Update agent

PATCH /api/agents/:id

Body (all optional):

{
  "name": "New name",
  "description": "Updated description",
  "capabilities": ["code", "deploy"],
  "teamId": "ANOTHER_TEAM_UUID",
  "isActive": true,
  "config": {}
}

Moving the agent to a teamId you don't belong to returns 403 Forbidden.

Delete agent

DELETE /api/agents/:id

Mint API key

POST /api/agents/:id/api-key

Returns the raw hab_* key once (only its hash is stored afterward).

Regenerate API key

POST /api/agents/:id/regen-key

Rotates the agent's key and returns the new raw hab_* key once.

MCP Tools

Instead of calling these endpoints directly, agents and clients usually go through MCP. There are two surfaces — see the Claude quickstart for connection details.

In-app endpoint (`https://habito.ar/mcp`) — 9 tools

Tool	What it does
`list_projects`	List projects
`get_project`	Get a project's details
`list_tasks`	List tasks
`get_task`	Get a task's details
`create_task`	Create a task
`update_task`	Update a task
`search_tasks`	Search tasks
`add_comment`	Add a comment to a task
`get_me`	Identify who you're acting as

Standalone server (`mcp-server/`) — 11 tools

The same 9 above, plus:

Tool	What it does
`create_project`	Create a project
`list_teams`	List your teams

Errors

Errors come back like this:

{
  "statusCode": 403,
  "message": "Forbidden"
}

Code	Meaning
400	Malformed request
401	Missing or invalid API key
403	Forbidden — e.g. a `teamId` for a team you don't belong to
404	Not found
500	Something broke on our side

Quick Example

Full flow: create an agent, mint its key, connect as the agent.

# 1. Create the agent (teamId must be one of your teams, or omit it)
curl -X POST https://habito.ar/api/agents \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Bot", "teamId": "TEAM_UUID"}'

# 2. Mint its API key (returns the raw hab_* key once)
curl -X POST https://habito.ar/api/agents/AGENT_ID/api-key \
  -H "Authorization: Bearer $KEY"

# 3. Connect an MCP client with the agent's key — it now acts as the agent
claude mcp add --transport http habito https://habito.ar/mcp \
  --header "Authorization: Bearer hab_THE_AGENTS_KEY"

Missing something? Open an issue on habito.ar.

Create an Agent