Getting started - HAI-Co²

The HAI-Co² backend is a FastAPI service. You can drive the whole co-construction loop over plain HTTP without the web frontend: start a conversation, stream an agent turn, and read back the shared workspace that the agent and the user built together. This page gets you to a working agent turn. Everything else in this guide goes deeper on one piece of it.

Before you start

You need a HAI-Co² account. Create it in the browser at haico.gr and click the verification link in your email.

You cannot register or log in from a script. POST /api/auth/register and POST /api/auth/login both verify a reCAPTCHA token that only a real browser can mint. Create your account once in the browser, then use a personal access token for everything after that. The reasoning is in ADR-0006.

Base URL

Every route is served under the /api prefix on the application host:

Environment	Base URL
Production	`https://haico.gr/api`
Development	`https://dev.haico.gr/api`
Local	`http://localhost:8000/api`

Your first agent turn

Create a token

Sign in at haico.gr, open Profile → API keys, and choose New key. Pick read,write access so you can run agent turns.The token is shown once, so copy it now:

export HAICO_TOKEN="haico_pat_..."

Full token guide →

Check that it works

curl -s https://haico.gr/api/auth/me \
  -H "Authorization: Bearer $HAICO_TOKEN"

{
  "id": 42,
  "username": "researcher",
  "email": "researcher@example.com",
  "role": "user",
  "email_verified": true
}

A 401 here means the token is wrong, revoked, or expired. Nothing below will work until this call succeeds.

Run a turn

Omit thread_id (or pass null) to start a new conversation.

curl -N -X POST https://haico.gr/api/query/stream_steps/sse \
  -H "Authorization: Bearer $HAICO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Draft a one-paragraph summary of the Apollo programme.", "thread_id": null}'

The response is a stream. The first event carries the thread_id you reuse on later turns, and the stream ends with complete:

data: {"type": "conversation_info", "thread_id": "th_3173225a...", "title": "..."}

data: {"type": "step", "thread_id": "...", "step": {...}}

data: {"type": "complete"}

Full streaming contract →

Read back what the agent built

export THREAD_ID="th_3173225a..."   # from the conversation_info event

curl -s "https://haico.gr/api/workspace/$THREAD_ID/document" \
  -H "Authorization: Bearer $HAICO_TOKEN"

Full workspace guide →

Running a turn consumes LLM credits on every call and requires a read,write token.

Where to go next

Authentication

Token scopes, expiry, revocation, rate limits, and the error codes you will hit.

Endpoint groups

A map of the six route groups, so you know which one to reach for.

Streaming agent turns

The SSE contract in full: event types, error handling, and choosing a model.

Reading the workspace

Objective, document, plan, preferences, and artifacts.

API-only clients

What the browser does for you, what it does not, and the three gaps that matter.

Recipes

A full two-turn loop in Python, and a token check for CI.

The per-endpoint reference (every parameter, request and response schema, and a “try it” playground) is generated from the OpenAPI spec and lives in the Endpoints section of this tab. Treat it as the source of truth for field-level detail.

​Before you start

​Base URL

​Your first agent turn

​Where to go next

Authentication

Endpoint groups

Streaming agent turns

Reading the workspace

API-only clients

Recipes

Before you start

Base URL

Your first agent turn

Where to go next