> ## Documentation Index
> Fetch the complete documentation index at: https://dev.haico.gr/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Make your first authenticated call and run your first agent turn in about five minutes.

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](https://haico.gr) and click the
verification link in your email.

> [!WARNING]
>
> **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](/docs/adr/0006-programmatic-api-access.md).

## 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

**1. Create a token**

Sign in at [haico.gr](https://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:

```bash theme={null}
export HAICO_TOKEN="haico_pat_..."
```

[Full token guide →](/docs/api-guide/authentication.md)

**2. Check that it works**

```bash theme={null}
curl -s https://haico.gr/api/auth/me \
  -H "Authorization: Bearer $HAICO_TOKEN"
```

```json theme={null}
{
  "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.

**3. Run a turn**

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

```bash theme={null}
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 →](/docs/api-guide/streaming-turns.md)

**4. Read back what the agent built**

```bash theme={null}
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 →](/docs/api-guide/workspace.md)

> [!WARNING]
>
> Running a turn consumes LLM credits on every call and requires a `read,write` token.

## Where to go next

> **[Authentication](/docs/api-guide/authentication.md)**
>
> Token scopes, expiry, revocation, rate limits, and the error codes you will hit.

> **[Endpoint groups](/docs/api-guide/endpoint-groups.md)**
>
> A map of the six route groups, so you know which one to reach for.

> **[Streaming agent turns](/docs/api-guide/streaming-turns.md)**
>
> The SSE contract in full: event types, error handling, and choosing a model.

> **[Reading the workspace](/docs/api-guide/workspace.md)**
>
> Objective, document, plan, preferences, and artifacts.

> **[API-only clients](/docs/api-guide/api-only-clients.md)**
>
> What the browser does for you, what it does not, and the three gaps that matter.

> **[Recipes](/docs/api-guide/recipes.md)**
>
> A full two-turn loop in Python, and a token check for CI.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.