> ## 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).
</Warning>

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

<Steps>
  <Step title="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)
  </Step>

  <Step title="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.
  </Step>

  <Step title="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)
  </Step>

  <Step title="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)
  </Step>
</Steps>

<Warning>
  Running a turn consumes LLM credits on every call and requires a `read,write` token.
</Warning>

## Where to go next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/api-guide/authentication">
    Token scopes, expiry, revocation, rate limits, and the error codes you will hit.
  </Card>

  <Card title="Endpoint groups" icon="map" href="/docs/api-guide/endpoint-groups">
    A map of the six route groups, so you know which one to reach for.
  </Card>

  <Card title="Streaming agent turns" icon="bolt" href="/docs/api-guide/streaming-turns">
    The SSE contract in full: event types, error handling, and choosing a model.
  </Card>

  <Card title="Reading the workspace" icon="folder-open" href="/docs/api-guide/workspace">
    Objective, document, plan, preferences, and artifacts.
  </Card>

  <Card title="API-only clients" icon="robot" href="/docs/api-guide/api-only-clients">
    What the browser does for you, what it does not, and the three gaps that matter.
  </Card>

  <Card title="Recipes" icon="code" href="/docs/api-guide/recipes">
    A full two-turn loop in Python, and a token check for CI.
  </Card>
</CardGroup>

<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.
</Note>