Flat REST API SDKs

We publish and maintain four clients for the Flat REST API. Each one is generated from our public OpenAPI specification 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 3.11 – 3.13
💛 JavaScript & TypeScript	npm install flat-api		Node 22, 24
💎 Ruby	gem install flat_api		Ruby 3.3, 3.4
🐘 PHP	composer require 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 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 to get started. It behaves like an OAuth access token scoped to your own account.

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)

import { FlatClient } from 'flat-api';

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

require 'flat_api'

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

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 supports:

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	Releases
JavaScript	FlatIO/api-client-js	Releases
Ruby	FlatIO/api-client-ruby	Releases
PHP	FlatIO/api-client-php	Releases