---
url: https://flat.io/developers/docs/api/sdks.md
description: Official Flat API clients for Python, JavaScript, Ruby and PHP.
---

# Flat REST API SDKs

We publish and maintain four clients for the [Flat REST API](index.html). Each one is generated
from our [public OpenAPI specification](https://github.com/FlatIO/api-reference) and released
automatically when that specification changes, so a client never drifts from the API it describes.

| | Install | Latest | Requires |
|---|---|---|---|
| 🐍 **Python** | `pip install flat-api` | [![Python on its registry](https://img.shields.io/pypi/v/flat-api?style=flat-square\&logo=pypi\&logoColor=white\&color=3775A9\&label=)](https://pypi.org/project/flat-api/) | Python 3.11 – 3.13 |
| 💛 **JavaScript & TypeScript** | `npm install flat-api` | [![JavaScript & TypeScript on its registry](https://img.shields.io/npm/v/flat-api?style=flat-square\&logo=npm\&logoColor=white\&color=CB3837\&label=)](https://www.npmjs.com/package/flat-api) | Node 22, 24 |
| 💎 **Ruby** | `gem install flat_api` | [![Ruby on its registry](https://img.shields.io/gem/v/flat_api?style=flat-square\&logo=rubygems\&logoColor=white\&color=CC342D\&label=)](https://rubygems.org/gems/flat_api) | Ruby 3.3, 3.4 |
| 🐘 **PHP** | `composer require flat/api` | [![PHP on its registry](https://img.shields.io/packagist/v/flat/api?style=flat-square\&logo=packagist\&logoColor=white\&color=F28D1A\&label=)](https://packagist.org/packages/flat/api) | PHP 8.2 – 8.4 |

The version badges read from each registry, so they are current whatever this page says.

Only runtimes still supported upstream are tested. When a version reaches its end of life we drop
it in the next major release of the client.

## What the clients do for you

The Flat API has a few behaviours that are easy to get wrong by assuming convention. Each client
handles them for you.

* **Typed errors.** Branch on the error, not the status code. Rate limiting and authorization
  failures both return HTTP 403, so the status alone cannot tell them apart.
* **Automatic retries.** Rate limits and server errors are retried with backoff. Flat sends no
  `Retry-After` header, so the clients read [`X-RateLimit-Reset`](rate-limits.html) instead.
* **Automatic pagination.** Collection endpoints are cursor-paginated with the cursor in a `Link`
  header. You get an iterator and never touch a cursor.
* **OAuth2 built in.** Authorization URLs, code exchange, and token refresh when a token expires.
* **Full type information**, so your editor and your coding assistant both know the API.

## Your first call

Create a [Personal Access Token](https://flat.io/developers/apps) to get started. It behaves like
an OAuth access token scoped to your own account.

```python
from flat_api import FlatClient
from flat_api.api.account_api import AccountApi

client = FlatClient(access_token="YOUR_TOKEN")
print(AccountApi(client.api_client).get_authenticated_user().username)
```

```ts
import { FlatClient } from 'flat-api';

const client = new FlatClient({ accessToken: 'YOUR_TOKEN' });
console.log((await client.account.getAuthenticatedUser()).username);
```

```ruby
require 'flat_api'

client = FlatApi::FlatClient.new(access_token: 'YOUR_TOKEN')
puts client.account.get_authenticated_user.username
```

```php
use Flat\APIClient\FlatClient;

$client = new FlatClient(accessToken: 'YOUR_TOKEN');
echo $client->account()->getAuthenticatedUser()->getUsername(), PHP_EOL;
```

Each repository carries a `QUICKSTART.md` that goes from installation to a first call, and a
per-operation reference generated from the specification.

## Another language

The specification is public and standard, so you can generate a client for any language
[openapi-generator](https://openapi-generator.tech) supports:

```bash
openapi-generator generate \
  -i https://flat.io/developers/docs/openapi.yaml \
  -g <language> -o ./flat-client
```

The four clients above are generated the same way, with the ergonomic layer described earlier added
on top.

## Source

| | | |
|---|---|---|
| Python | [FlatIO/api-client-python](https://github.com/FlatIO/api-client-python) | [Releases](https://github.com/FlatIO/api-client-python/releases) |
| JavaScript | [FlatIO/api-client-js](https://github.com/FlatIO/api-client-js) | [Releases](https://github.com/FlatIO/api-client-js/releases) |
| Ruby | [FlatIO/api-client-ruby](https://github.com/FlatIO/api-client-ruby) | [Releases](https://github.com/FlatIO/api-client-ruby/releases) |
| PHP | [FlatIO/api-client-php](https://github.com/FlatIO/api-client-php) | [Releases](https://github.com/FlatIO/api-client-php/releases) |