Flat API client for Python

Official client for the Flat REST API, generated from Flat's public OpenAPI specification and kept current automatically.

pip install flat-api

from flat_api import FlatClient

client = FlatClient(access_token="YOUR_TOKEN")
me = client.api_client  # generated APIs hang off here

Get a token in seconds with a Personal Access Token; it works exactly like an OAuth access token for your own account.

What this client does for you

Typed errors. Branch on the error, not the status code. Flat returns HTTP 403 for both rate limiting and authorization failures, so status alone cannot tell them apart.
Automatic retries. Rate limits and server errors are retried with backoff. Flat sends no Retry-After, so the client reads X-RateLimit-Reset instead.
Automatic pagination. Eight collection endpoints are cursor-paginated with the cursor in a Link header. You get an iterator; you never touch a cursor.
OAuth2 built in. Authorization URLs, code exchange and transparent token refresh.
Full type information, so your editor and your coding assistant both know the API.

Pagination

from flat_api import paginate

for score in paginate(api.get_user_scores_with_http_info, user="me"):
    print(score.title)

Errors

from flat_api import FlatRateLimitError, FlatNotFoundError

try:
    ...
except FlatRateLimitError as exc:
    print("retry after", exc.reset)
except FlatNotFoundError:
    print("no such score")

Asynchronous use

from flat_api import AsyncFlatClient

client = AsyncFlatClient(access_token="YOUR_TOKEN")
# every operation is awaitable

Supported versions

Python 3.11, 3.12 and 3.13. Versions past their upstream end of life are not supported; see MIGRATION.md if you are on an older runtime.

Documentation

Verifying this package

Every release carries a signed provenance attestation linking the package back to the commit, the workflow run that built it, and the API specification version it was generated from.

pip download --no-deps flat-api
gh attestation verify flat_api-*.whl --repo FlatIO/api-client-python

Published through PyPI trusted publishing: no long-lived token exists that could publish under this name.

How this client is maintained

Generated from the public specification published at FlatIO/api-reference. A new specification release regenerates, validates and publishes this package automatically, so it never drifts from the API.

Files under docs/reference/ and the client sources are generated: edit the generator configuration in tools/, not the output.

License

Apache 2.0. See LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flat_api-2.0.1.tar.gz (374.7 kB view details)

Uploaded Sep 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

flat_api-2.0.1-py3-none-any.whl (1.2 MB view details)

Uploaded Sep 10, 2026 Python 3

File details

Details for the file flat_api-2.0.1.tar.gz.

File metadata

Download URL: flat_api-2.0.1.tar.gz
Upload date: Sep 10, 2026
Size: 374.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for flat_api-2.0.1.tar.gz
Algorithm	Hash digest
SHA256	`5773d8fd5ea215f3695e3c39bcaa6dc5845c5c41fc3599a4c3145c8094d74f53`
MD5	`151b299c5d590553628a2d805a83a0fe`
BLAKE2b-256	`326bfc07da2aa3f2e46e3ffc0f855eefe9ebc3623a0398f2b88cffd464e9df8a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for flat_api-2.0.1.tar.gz:

Publisher: release.yml on FlatIO/api-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: flat_api-2.0.1.tar.gz
- Subject digest: 5773d8fd5ea215f3695e3c39bcaa6dc5845c5c41fc3599a4c3145c8094d74f53
- Sigstore transparency entry: 2784694953
- Sigstore integration time: Sep 10, 2026
Source repository:
- Permalink: FlatIO/api-client-python@40bbbeb388b318510ec0ce48e165f2c8bc5a083b
- Branch / Tag: refs/tags/2.0.1
- Owner: https://github.com/FlatIO
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@40bbbeb388b318510ec0ce48e165f2c8bc5a083b
- Trigger Event: push