# Introduction

> What the AYETO API offers, how it is shaped and how to make the first request.

The AYETO API lets your application do what a user does in the AYETO app: chat with
models and assistants, read and manage conversations, run workflows, decide workflow
approvals and work with booster panel databases. Every request acts as the user who
owns the API key, with that user's permissions and credits.

## Base URL

All endpoints live under one base URL:

```text
https://ayeto.ai/api/v3
```

The API is versioned in the path. Version 3 is the API for integrations; other
paths you may see in the AYETO app (such as `/api/v1`) are internal to the app and
can change without notice.

## How the API is shaped

- **RPC over POST.** Almost every endpoint is a `POST` with a JSON body, named after
  what it does: `/conversation/find`, `/conversation/count`, `/workflow/run`. There are
  no `GET /resource/{id}` or `DELETE` routes. See [Requests](conventions.md#requests).
- **API key authentication.** Send the key in the `uni-api-key` header. Each key carries
  scopes that decide which endpoints it may call. See [Authentication](authentication.md).
- **Lists are queried with one body shape.** `find` and `count` endpoints take filters,
  sorting and paging in the body. See [Querying lists](conventions.md#querying-lists).
- **Errors are JSON** of the form `{"detail": "..."}` with a meaningful HTTP status.
  See [Errors](conventions.md#errors).
- **Long answers stream.** Chat answers and workflow runs can be streamed as they are
  produced. See [Streaming](streaming.md).

## Quick start

1. In the AYETO app open **Profile → API keys**, create a key with the
   **AYETO chat** scope and copy it. The key is shown only once.
2. Keep it in an environment variable:

   ```bash
   export AYETO_API_KEY="ayeto-..."
   ```

3. Ask a model a question:

   ```bash
   curl -X POST "https://ayeto.ai/api/v3/chat" \
     -H "uni-api-key: $AYETO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model": "gpt-5-mini", "message": "Summarize the benefits of unit tests in three bullet points."}'
   ```

   The answer comes back as a message object; its `content` is Markdown. To continue
   a conversation, generate a UUID yourself, send it as `conversation_id` with the first
   message and again with every follow-up (see [Chat](chat.md)).
   The model ids you can use are listed by [`/ai_model/get_all`](models-and-tools.md).

## What to read next

| Page | What it covers |
|---|---|
| [Authentication](authentication.md) | API keys, scopes, authentication errors |
| [Conventions](conventions.md) | Request shape, common fields, filters, paging, errors, rate limits |
| [Streaming](streaming.md) | Reading streamed chat answers |
| [Chat](chat.md) | Sending messages to models and assistants |
| [Conversations](conversations.md) | Listing, reading and deleting conversations |
| [Assistants](assistants.md) | Listing assistants and their avatars |
| [Models and tools](models-and-tools.md) | The AI models and tools available to the key's user |
| [Workflows](workflows.md) | Running, editing and publishing workflows, approvals, webhooks |
| [Booster database](booster-database.md) | Records in booster panel databases |
| [Account](account.md) | Credits, organization membership, usage cost, API version |
| [Files and media](files-and-media.md) | Extracting text from files, text to speech |
| [Changelog](changelog.md) | Changes to the API |