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 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.
Organization credits pay for work done in an organization, for example a chat 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.

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

Returns the personal credit balance of the API key's user. Organization balances are returned by 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.

Errors

This endpoint has no endpoint-specific errors. Authentication, rate limit and server errors are described in conventions.

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

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

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

Returns the credits the API key's user spent in one conversation: 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.

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

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"
}

Credits #

Get the credit balance #

Request #

Response #

Errors #

Example #

List organization memberships #

Request #

Response #

Errors #

Example #

Get the cost of a conversation #

Request #

Response #

Errors #

Example #

Get the server version #

Request #

Response #

Example #

Credits

Get the credit balance

Request

Response

Errors

Example

List organization memberships

Request

Response

Errors

Example

Get the cost of a conversation

Request

Response

Errors

Example

Get the server version

Request

Response

Example