Cloud API

Everything you do in the Cloud app is also available over HTTP at https://haarness.ai/api/v1. This page walks through a script that starts a workspace with a task, reads the answer, then schedules the task for every morning. The full reference is the OpenAPI document. The SDKs wrap the same calls.

Before you start

1. Create an API key with the Cloud automation preset. It has every permission this page uses.
2. Put it in your environment as HAARNESS_API_KEY. Never put it in a URL or a log.

The examples use curl, jq and uuidgen in bash or zsh:

export HAARNESS=https://haarness.ai
auth=(-H "Authorization: Bearer $HAARNESS_API_KEY")

Start a workspace with a task

CREATED=$(curl -sf "${auth[@]}" -X POST "$HAARNESS/api/v1/workspaces" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title": "Nightly review", "initialPrompt": {"text": "Summarise the commits from yesterday."}}')
WORKSPACE=$(jq -r .workspace.id <<<"$CREATED")
CHAT=$(jq -r .workspace.launch.chatId <<<"$CREATED")

The answer (202) holds the new workspace and the operation that starts it. The workspace starts straight away. Cloud sends the message to a new chat as soon as the workspace is ready, even if your script has already exited. $CHAT is that chat.

configuration and environment set the workspace's settings and secret environment values; the OpenAPI document describes them.

Wait for the answer

while :; do
  STATUS=$(curl -sf "${auth[@]}" "$HAARNESS/api/v1/workspaces/$WORKSPACE" | jq -r .launch.status)
  case $STATUS in pending|running) sleep 10 ;; *) break ;; esac
done
echo "$STATUS"

On needs_attention, open the chat in the Cloud app and answer there, or answer over the API as on a local server, using the ticket below.

The workspace's own state is in observedState: starting, running, stopped, failed and so on.

Read the answer

A workspace's chats are reached through its own address, with a short-lived ticket:

ATTACH=$(curl -sf "${auth[@]}" -X POST "$HAARNESS/api/v1/workspaces/$WORKSPACE/attach")
GATEWAY=$(jq -r .gatewayUrl <<<"$ATTACH")
ticket=(-H "Authorization: Bearer $(jq -r .ticket <<<"$ATTACH")")

curl -sf "${ticket[@]}" "$GATEWAY/v1/threads/$CHAT/items" \
  | jq -r '.[] | select(.data.type == "assistant_message") | .data.text'

Attaching works while the workspace is running. If it has gone to sleep or was stopped, POST to its /start and wait for running first. A ticket lasts up to eight hours (expiresAt) and stops working when the workspace restarts or the key is rotated or revoked. Attach again whenever you need a new one.

With the ticket, the workspace answers like a local Haarness server: the same calls reach its chats, files, terminal and changes. Follow the agent live with curl -N "${ticket[@]}" "$GATEWAY/v1/events".

Send another message

TURN=$(curl -sf "${ticket[@]}" -X POST "$GATEWAY/v1/threads/$CHAT/turns" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"Which change is the riskiest?\", \"requestId\": \"$(uuidgen)\"}" | jq -r .id)
curl -sf "${ticket[@]}" "$GATEWAY/v1/turns/$TURN/wait?timeout_ms=120000" | jq -r .status

Then read the items again. A wait gives up after five minutes at most; call it again if the turn is still running.

To open another chat in the same workspace, POST "$GATEWAY/v1/threads" with {"title": "…"} and use the id it returns. A workspace's chats share its files.

For a workspace you started without initialPrompt, wait until observedState is running, then attach and create a chat this way.

Schedule it

Run the same prompt in that chat every weekday at 08:00, Paris time:

curl -sf "${auth[@]}" -X POST "$HAARNESS/api/v1/schedules" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"workspaceId\": \"$WORKSPACE\", \"chatId\": \"$CHAT\", \"name\": \"Morning review\",
       \"prompt\": \"Summarise yesterday's commits.\", \"cron\": \"0 8 * * 1-5\", \"timezone\": \"Europe/Paris\"}"

To check a timing before you save it, GET /api/v1/schedules/preview?cron=0%208%20*%20*%201-5&timezone=Europe/Paris returns the next runs (count up to 20). A run marked "shifted": true falls on a night when the clocks go forward. See Schedule prompts for how time zones work.

Manage workspaces and Cloud agents

A workspace keeps its files, and the storage they take, until you delete it; sleeping does not free storage. Workspaces have no archived state. Changing a workspace's configuration or environment with PATCH needs its current version and a sleeping workspace. Cloud agents are created, changed and deleted with POST /api/v1/cloud-agents, PUT and DELETE /api/v1/cloud-agents/{id}.

Handle errors, retries and rate limits

• Retry safely. Send an Idempotency-Key header with every POST that creates or runs something. If a request times out, repeat it with the same key and body: you get the first answer instead of a second workspace. The same key with a different body fails with idempotency_mismatch.
• Match errors on code. Errors look like {"code": "insufficient_scope", "message": "…", "requestId": "…", "retryable": false}. The message is for people and can change. Retry only when retryable is true, and quote the requestId when you contact support.
• Page through lists. Lists return {"items": […], "nextCursor": "…"}. Pass ?cursor= with the nextCursor to get the next page, until nextCursor is null.
• Respect 429. Wait for the number of seconds in the Retry-After header, then try again.

Permissions

Pick only what your script needs when you create the key:

A key belongs to one account. It stops working when it expires, when it is revoked, or when the person who created it leaves the account or becomes a Viewer. Whatever its permissions, a key cannot create or change API keys, change payment settings or manage members. An account can have up to 100 active keys.