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

# Quickstart

> List your agents, send a message, read the reply. Five minutes from zero to a working integration.

This walkthrough takes you from a fresh API key to a working chat round-trip in five minutes.

## 0. Prerequisites

* A workspace with at least one **published** agent (use Studio to create one if you don't have any).
* A workspace API key (see [Authentication](/en/api-reference/authentication)).

Export the key once so the snippets below are copy-pasteable:

```bash theme={null}
export GENNIA_API_KEY="gsk_your_key_here"
```

## 1. Verify the key

The `health` endpoint validates the key and returns the workspace it's bound to.

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/health" \
  -H "X-Api-Key: $GENNIA_API_KEY"
```

```json Response theme={null}
{
  "status": "ok",
  "workspacePublicId": "9c3a4d22-1a8d-4b3f-9b1e-7a0f0c4f3e21",
  "apiKeyPublicId": "7f2b1c44-6e90-4d2a-83b5-c1f2d3a4b5c6"
}
```

A non-`ok` response — or any `401` — means **stop**. Re-check `Authentication` before continuing.

## 2. List your agents

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/agents" \
  -H "X-Api-Key: $GENNIA_API_KEY"
```

The response is paginated. Save the `publicId` of an agent that has `status: "published"` — you'll need it next.

```json Response (trimmed) theme={null}
{
  "items": [
    {
      "publicId": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Support Bot",
      "status": "published",
      "description": "Answers questions about billing and account access."
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}
```

## 3. Send a message

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/agents/$AGENT_ID/messages" \
  -H "X-Api-Key: $GENNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hi, can you summarize my account status?",
    "externalUserId": "user_42"
  }'
```

The endpoint blocks until the agent finishes (or `timeoutSeconds` expires — default is 60 seconds). The response contains the reply text, the conversation ID, token usage, and cost.

```json Response (trimmed) theme={null}
{
  "conversationId": "9c3a4d22-1a8d-4b3f-9b1e-7a0f0c4f3e21",
  "messages": [
    {
      "role": "assistant",
      "content": "Your account is active and you have 4,500 credits remaining…"
    }
  ],
  "usage": {
    "inputTokens": 245,
    "outputTokens": 89,
    "totalCost": 0.0023
  }
}
```

## 4. Continue the conversation

Pass back the `conversationId` from step 3 to keep the same thread:

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/agents/$AGENT_ID/messages" \
  -H "X-Api-Key: $GENNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"content\": \"What about my next renewal?\",
    \"conversationId\": \"$CONVERSATION_ID\"
  }"
```

## 5. Streaming responses

For interactive UIs, use the SSE endpoint instead of the blocking one. Same body shape; response is `text/event-stream`.

```bash theme={null}
curl -N "https://api.gennia.ai/public/api/v1/agents/$AGENT_ID/messages/stream" \
  -H "X-Api-Key: $GENNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Tell me a long story"}'
```

You'll receive a stream of events: `conversation-id`, repeated `text-delta`, then `debug-info` with token usage and cost.

## Next

<CardGroup cols={2}>
  <Card title="Conventions" icon="list-check" href="/en/api-reference/conventions/pagination">
    Pagination, error format, common headers.
  </Card>

  <Card title="Full reference" icon="book" href="/en/api-reference/introduction">
    Every endpoint with try-it-out and schemas. Browse under "Endpoints" in the sidebar.
  </Card>
</CardGroup>