Flat API client for Ruby

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

gem install flat_api

require 'flat_api'

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

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

client.paginate(:list_collections, parent: 'user') do |collection|
  puts collection.title
end

paginate takes any operation: positional arguments are its path parameters, keywords its query parameters. It follows the cursor for you and stops at the last page.

Errors

begin
  # ...
rescue FlatApi::FlatRateLimitError => e
  puts "retry after #{e.reset}"
rescue FlatApi::FlatNotFoundError
  puts 'no such score'
end

Asynchronous use

Synchronous only: async is not idiomatic in Ruby for this shape of client.

Supported versions

Ruby 3.3 and 3.4. Versions past their upstream end of life are not supported; see MIGRATION.md if you are on an older runtime.

Documentation

• Quickstart, install to first call
• Per-operation reference, generated
• API documentation
• Migrating from 0.3.x

Verifying this gem

Published through RubyGems trusted publishing, so no long-lived API key exists that could publish under this name. The release workflow is the only publisher, and each release is tied to the commit and the API specification version it was generated from.

gem fetch flat_api
gem spec flat_api-*.gem

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.