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

# Using the API

> Conventions that apply to every endpoint — base URL, auth, envelopes, errors, pagination, and streaming.

The endpoint pages in this section are generated from the OpenAPI contract. This page covers
the conventions that apply across all of them.

## Base URL

```
https://builder.flowyte.com/api/v1
```

The API is versioned in the path and additive within `v1`.

## Authentication

Send a secret key as a bearer token: `Authorization: Bearer flowyte_sk_…`. See
[Authentication](/get-started/authentication) for keys, scopes, and the publishable-key path
for the chat widget.

## Response envelope

Successful responses are wrapped in an `ApiResponse<T>` envelope:

```json theme={null}
{ "success": true, "data": { /* the resource */ } }
```

List responses use `PaginatedResponse<T>` with **cursor** pagination — pass the returned cursor
to fetch the next page rather than page numbers.

## Errors

Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem+json
(`application/problem+json`):

```json theme={null}
{
  "type": "https://docs.flowyte.com/errors/no_published_version",
  "title": "No published version",
  "status": 409,
  "detail": "agent has no published version; publish it or retry with draftMode:true"
}
```

Treat the `type` / `status` pair as the recovery contract.

## Streaming (SSE)

Streaming endpoints (simulate, assist, probe) return `text/event-stream`. Each frame is
`event:<type>\ndata:<json>\n\n`; the stream terminates with `event: done` (or `event: error`).
Consume them with `fetch()` streaming so your `Authorization` header attaches.

## Idempotency

Money-moving endpoints accept an idempotency key so a retry replays the original result instead
of charging twice.

## Rate limits

The API is rate-limited per organization. Limits are generous for normal use; if you hit one,
back off and retry.