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

# OpenAPI

> OpenAPI specification and code generation

The Avala API publishes a full [OpenAPI 3.1](https://www.openapis.org/) specification. You can use it to explore the API interactively, generate client libraries in any language, or integrate with API tooling like Postman and Insomnia.

## Specification URL

The latest OpenAPI spec is always available at:

```
https://api.avala.ai/docs/api/openapi.json
```

You can download it directly:

```bash theme={null}
curl -o openapi.json https://api.avala.ai/docs/api/openapi.json
```

## Interactive Documentation

Browse the full API reference, try out requests, and inspect schemas in the interactive docs:

<CardGroup cols={1}>
  <Card title="" icon="browser" href="https://api.avala.ai/docs/api/">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Interactive API Docs</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Explore every endpoint, see request and response schemas, and make live API calls directly from your browser.</p>
  </Card>
</CardGroup>

## Code Generation

Use the OpenAPI spec to generate a typed client in your language of choice. Below are examples for popular code generators.

<Tip>
  The generated clients below (e.g., `avala_client`, `openapi-fetch`) are **separate from the official Avala SDKs** (`avala` for Python, `@avala-ai/sdk` for TypeScript). For most use cases, we recommend the official SDKs — see [Python SDK](/docs/sdks/python) and [TypeScript SDK](/docs/sdks/typescript). Code generation is useful when you need a client in a language we don't have an official SDK for, or want full type coverage of every endpoint.
</Tip>

### Python

Generate a Python client using [openapi-python-client](https://github.com/openapi-generators/openapi-python-client):

```bash theme={null}
pip install openapi-python-client

openapi-python-client generate \
  --url https://api.avala.ai/docs/api/openapi.json \
  --output-path ./avala-client
```

This produces a fully typed Python package with Pydantic models and `httpx`-based HTTP methods. Note that this generated `avala_client` package is distinct from the official `avala` SDK.

```python theme={null}
from avala_client import Client
from avala_client.api.datasets import list_datasets

client = Client(base_url="https://api.avala.ai/api/v1")

response = list_datasets.sync(client=client)
```

### TypeScript

Generate TypeScript types and a fetch client using [openapi-typescript](https://github.com/openapi-ts/openapi-typescript):

```bash theme={null}
npx openapi-typescript https://api.avala.ai/docs/api/openapi.json \
  -o ./src/avala-api.d.ts
```

Then use the generated types with your preferred HTTP client:

```typescript theme={null}
import type { paths } from "./avala-api";
import createClient from "openapi-fetch";

const client = createClient<paths>({
  baseUrl: "https://api.avala.ai/api/v1",
  headers: {
    "X-Avala-Api-Key": process.env.AVALA_API_KEY!,
  },
});

const { data, error } = await client.GET("/datasets");
```

### Go

Generate a Go client using [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen):

```bash theme={null}
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

oapi-codegen \
  -package avala \
  -generate types,client \
  https://api.avala.ai/docs/api/openapi.json > avala.gen.go
```

Then use the generated client:

```go theme={null}
package main

import (
	"context"
	"fmt"
	"os"

	"your-module/avala"
)

func main() {
	client, _ := avala.NewClientWithResponses(
		"https://api.avala.ai/api/v1",
		avala.WithRequestEditorFn(func(ctx context.Context, req *http.Request) error {
			req.Header.Set("X-Avala-Api-Key", os.Getenv("AVALA_API_KEY"))
			return nil
		}),
	)

	resp, _ := client.ListDatasetsWithResponse(context.Background())
	fmt.Println(resp.JSON200)
}
```

## Other Tools

The OpenAPI spec works with any tool that supports the OpenAPI standard:

| Tool                                                         | Use Case                                                       |
| ------------------------------------------------------------ | -------------------------------------------------------------- |
| [Postman](https://www.postman.com/)                          | Import the spec to create a ready-made collection for testing. |
| [Insomnia](https://insomnia.rest/)                           | Import the spec for quick API exploration.                     |
| [Swagger Codegen](https://swagger.io/tools/swagger-codegen/) | Generate clients in 40+ languages.                             |
| [Stoplight](https://stoplight.io/)                           | Build internal API docs and mocks from the spec.               |

<Tip>
  The OpenAPI specification is updated automatically whenever the API changes. Always fetch the latest version from the spec URL to ensure your generated client stays in sync.
</Tip>