# Account

> Read the credit balance, the organization memberships and conversation costs of the API key's user, and the server version.

These endpoints describe the account behind the API key: how many credits it has, which
organizations it belongs to and what a conversation cost. The version endpoint tells you
which AYETO release the server runs.

## Credits

Everything that uses an AI model (chat, image generation, speech, document conversion)
is paid in **credits**. The price of each call follows from the model used and the
amount of input and output it processed; see [models](models-and-tools.md#price-tiers)
for a relative price indication.

There are two kinds of balance:

- **Personal credits** belong to the user. They pay for everything done outside an
  organization. Read them with [get credit balance](#get-the-credit-balance).
- **Organization credits** pay for work done in an organization, for example a
  [chat](chat.md) request with an `organization_id`. Depending on how the organization is
  set up, a member either draws on the organization's shared balance or has an individual
  budget within it. Read them with [list organization memberships](#list-organization-memberships).

A request is refused when the balance it would draw on is used up. The check happens
before the work starts, and the actual cost is charged when the work is done, so a
balance can end slightly below zero. When a balance runs out, the request fails with
`422` and the detail `not enough user credit` or `not enough organization credit`.

Credits are added in the AYETO app.

## Get the credit balance

| | |
|---|---|
| Endpoint | `POST /api/v3/user_credit/get_self` |
| Scope | any API key |
| Rate limit | [default](conventions.md#rate-limits) |

Returns the personal credit balance of the API key's user. Organization balances are
returned by [list organization memberships](#list-organization-memberships).

`GET /api/v3/user_credit/get_self` still works and returns the same; both methods share
one rate limit counter.

### Request

No body is needed and no parameters. A JSON body, if you send one, is ignored.

### Response

`200 OK` with:

| Field | Type | Description |
|---|---|---|
| `credits` | number | Personal credit balance. Can be slightly negative, see [credits](#credits). |

### Errors

This endpoint has no endpoint-specific errors. Authentication, rate limit and server
errors are described in [conventions](conventions.md#errors).

### Example

```bash
curl -X POST "https://ayeto.ai/api/v3/user_credit/get_self" \
  -H "uni-api-key: $AYETO_API_KEY"
```

```json
{
  "credits": 1843.27
}
```

## List organization memberships

| | |
|---|---|
| Endpoint | `POST /api/v3/organization/membership/get_self` |
| Scope | any API key |
| Rate limit | [default](conventions.md#rate-limits) |

Returns the organizations the API key's user is a member of, with the user's role and
the credits available to the user in each. Use `organization_id` from here as the
`organization_id` of a [chat](chat.md) request to work, and pay, within that organization.

### Request

No body is needed.

### Response

`200 OK` with an array of memberships, empty when the user is not a member of any
organization:

| Field | Type | Description |
|---|---|---|
| `organization_id` | UUID | The organization. |
| `organization_name` | string | Name of the organization. |
| `user_id` | UUID | The API key's user. |
| `role` | string | The user's role: `ayeto-org-admin` (administrator), `ayeto-org-member` (member) or `ayeto-org-guest` (guest). |
| `individual_budget` | boolean | `true` when the user has an individual budget in the organization; `false` when the user draws on the organization's shared balance. |
| `credits` | number | Credits available to the user in this organization: the individual budget when `individual_budget` is `true`, otherwise the organization's shared balance. |
| `is_partner_admin` | boolean | `true` for an administrator membership held on behalf of the partner that manages the organization. |
| `has_logo` | boolean | Whether the organization has a logo. |
| `logo_id` | UUID or null | Identifier of the logo file. |
| `logo_url` | string | Public URL of the logo, empty when there is none. |

### Errors

This endpoint has no endpoint-specific errors. Authentication, rate limit and server
errors are described in [conventions](conventions.md#errors).

### Example

```bash
curl -X POST "https://ayeto.ai/api/v3/organization/membership/get_self" \
  -H "uni-api-key: $AYETO_API_KEY"
```

```json
[
  {
    "organization_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "organization_name": "Northwind Trading",
    "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e",
    "role": "ayeto-org-member",
    "individual_budget": false,
    "credits": 25210.5,
    "is_partner_admin": false,
    "has_logo": true,
    "logo_id": "0f9e8d7c-6b5a-4938-8271-605f4e3d2c1b",
    "logo_url": "https://ayeto.ai/api/v1/public/file/read?id=0f9e8d7c-6b5a-4938-8271-605f4e3d2c1b&secret=3b8f1c2d9e7a4b6c"
  }
]
```

## Get the cost of a conversation

| | |
|---|---|
| Endpoint | `POST /api/v3/usage/cost/conversation` |
| Scope | `ayeto.conversation` |
| Rate limit | [default](conventions.md#rate-limits) |

Returns the credits the API key's user spent in one [conversation](conversations.md):
the model calls of all its messages, including the tools that used AI models (image
generation, document reading, speech). Only the user's own spending is counted; in a
conversation other people also took part in, their usage is left out.

The cost is the sum of the credits recorded for each model call when it was charged, so
it equals what the user paid, also when a model's price has changed or the model has
been removed since.

A conversation that does not exist, or in which the user spent nothing, returns `0`.

### Request

| Field | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | UUID | Yes | The conversation. |

### Response

`200 OK` with:

| Field | Type | Description |
|---|---|---|
| `conversation_id` | UUID | The conversation from the request. |
| `total_cost` | number | Credits spent by the user in the conversation. |

### Errors

| Status | `detail` | Cause |
|---|---|---|
| `401` | `API key is invalid` | The key lacks the `ayeto.conversation` scope (and is not an all-scopes key), or is not valid. |
| `403` | `permission denied` | The user's account is not allowed to read usage data. |
| `422` | validation error | `conversation_id` is missing or not a UUID. |

Authentication, rate limit and server errors are described in
[conventions](conventions.md#errors).

### Example

```bash
curl -X POST "https://ayeto.ai/api/v3/usage/cost/conversation" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "5e4d3c2b-1a09-4f8e-b7d6-c5b4a3928170"}'
```

```json
{
  "conversation_id": "5e4d3c2b-1a09-4f8e-b7d6-c5b4a3928170",
  "total_cost": 12.4816
}
```

## Get the server version

| | |
|---|---|
| Endpoint | `POST /api/v3/version` |
| Scope | none, no API key needed |
| Rate limit | [static](conventions.md#rate-limits) |

Returns the version of the AYETO release the server runs. Use it for diagnostics and to
check that the server is reachable.

`GET /api/v3/version` still works and returns the same; both methods share one rate
limit counter (1,200 requests a minute per IP address), which is enough for health checks.

Every API response also carries the release in the `app-version` response header.

### Request

No body is needed and no parameters. A JSON body, if you send one, is ignored. The
`uni-api-key` header is not needed.

### Response

`200 OK` with:

| Field | Type | Description |
|---|---|---|
| `app_version` | string | The AYETO release, for example `0.20.7`. This is the version to report in support requests. |
| `version` | string | Version of the server framework. |
| `run_id` | string | Identifier of the running server process. It changes on every restart and differs between server instances. |
| `app_deployment` | string | Label of the deployment slot that answered (for example `BLUE` or `GREEN`), `UNKNOWN` when not set. |

### Example

```bash
curl -X POST "https://ayeto.ai/api/v3/version"
```

```json
{
  "version": "2.0.0",
  "run_id": "b7c6d5e4-f3a2-4b1c-8d9e-0f1a2b3c4d5e",
  "app_version": "0.20.7",
  "app_deployment": "BLUE"
}
```