Hania Code API

The terminal client is built on the public v1 surface, and any integrator can use the same endpoints. Authenticate with a hania_sk_ key as a bearer token; see Authentication & API keys.

API key abilities

Endpoints

Send a coding turn

POST /api/v1/chat/send-stream requires external_user_id, which scopes sessions to the person using your integration. Pass new_conversation to start a fresh session, or a conversation_id to continue one. The reply streams as server-sent events on the response.

These fields say where the code work happens. They're the only way to bind a conversation to a computer or server:

They're saved on the conversation, so later turns - including ones sent from the console - keep working on the same machine and folder without sending them again. A few things to know:

• They only take effect for an agent with Hania Code on. Sent to any other agent, they're saved but not used.
• They aren't checked when saved. A machine id from another account is accepted, then fails when the agent tries to use it.
• A conversation with nothing bound can't do any coding: every Hania Code action fails. Agent runs are different: one started with POST /api/v1/agents/{id}/trigger works on the computer where hania is open with that agent, as described in runs and teams, and fails with "no Hania Code session is open for this agent" when there isn't one.

Pair a server

POST /api/v1/machines with a name for the server pairs it and returns its id and a one-time token. Start the runner on the server with that token (see Servers), and send the id as code_machine_id. A name that's already taken returns 409. It needs an API key with chat:send, and on Free it's refused because Free includes no machines.

The terminal client calls the same endpoint with an extra install_id to register the computer it runs on. That form is for the terminal client; integrations should pair without it.

Approvals

When the agent proposes a change that has to ask (see approvals), the turn pauses. The pending request appears on GET /api/v1/hitl for the conversation, with the kind of change in tool_name, its details in tool_args, and the content to review in context:

The diffs come from git diff on the machine, in the usual diff --git form. If git isn't installed there, context is empty for writes, edits, and patches, so show the change from tool_args instead. Answer the request with:

curl -X POST https://app.hania.ai/api/v1/hitl/REQUEST_ID/respond \
  -H "Authorization: Bearer $HANIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve"}'

A pending row may also carry remember_rule, for example {"action": "bash", "target": "npm test", "label": "run npm test"}. When it's there, offer a second way to approve, labelled with label, and send {"action": "approve", "remember": true}. That exact file or command then runs with no card for the rest of the session. The field is absent when the rule can't be stated exactly, such as a patch over several files or a target holding * or ?; then offer the usual choices. remember is ignored on a denial, on other tools, and where no rule was offered, so don't send it with edited arguments. DELETE /api/v1/conversations/{id}/code-approvals clears what a session remembers.

action is approve, approve_edited, or deny, with an optional text (the reason, on a deny) and optional edited_args (your corrected version, with approve_edited). Only these fields of edited_args are used: path and content for a write; path, old_string, new_string, and replace_all for an edit; patch for a patch; command for both command types. The action itself can't be changed. The turn resumes on its own; receive the continuation on GET /api/v1/chat/stream rather than re-sending anything.

Sessions and stats

Sessions are ordinary conversations. GET /api/v1/conversations?external_user_id=… lists a user's sessions for a resume picker, and GET /api/v1/conversations/{id} returns the messages. GET /api/v1/chat/stats returns the conversation's token and cost figures.

Rollback

GET /api/v1/conversations/{id}/rewind lists the session's own prompts, oldest first, as the points you can roll back to. Each has a message_id, its content, created_at, and code_changes, which is true when that point has file changes to undo.

POST /api/v1/conversations/{id}/rewind with a message_id from that list and a mode rolls back to that point:

It returns files_restored, files_removed, and skipped_paths (a list of paths that weren't restored). When the conversation is rolled back, the conversation channel receives a resync event with the reason rewound, so any other window showing it reloads.

File changes can only be restored on the machine that made them, so that machine has to be online. POST /api/v1/conversations/{id}/truncate is still available when you only want to remove the messages after a given one; it never touches files.