---
url: https://docs.floored.app/reference/api.md
description: >-
  Create a developer key and read Ethscriptions, collections, profiles,
  activity, market, auction, search, and statistics data.
---

# Public API

Use the read-only floored v1 API to add indexed Ethscriptions and floored data to your own application.

<a class="status-chip" href="https://data.floored.app/gfy/docs">Open interactive API documentation</a>

## Make your first request

You need a verified Premium or Admin account to create and use a developer key.

1. Verify your wallet in floored.
2. Open [**Settings**](/features/settings#manage-developer-api-keys).
3. Find **Developer** and **API keys**.
4. Enter a descriptive name and choose **Create key**.
5. Copy the raw key before choosing **Done**. It appears only once.
6. Send the key in the `X-API-Key` header.

```bash
curl "https://api.floored.app/v1/ethscriptions?limit=20&sort=newest" \
  -H "X-API-Key: flr_sk_your_key"
```

The key starts with `flr_sk_`. floored stores a one-way digest and safe display information, not another copy of the raw value. Revoking a key is permanent.

Eligible accounts can create several keys, but quotas and rate limits apply to the owner across all keys.

## URLs and interactive reference

* Base URL: `https://api.floored.app/v1`
* Interactive documentation: `https://data.floored.app/gfy/docs`
* OpenAPI JSON: `https://data.floored.app/gfy/openapi.json`

`GET /v1/health` does not require a key. Production data endpoints require `X-API-Key`.

Use the OpenAPI document for the current operation list, parameters, and schemas.

## Choose a resource

v1 provides read operations for:

* Ethscriptions, existence checks, batches, ownership verification, comments, and activity
* Account Ethscriptions, collections, profile-topic comments, and activity
* Collection directory, details, items, traits, holders, statistics, and activity
* Ownership-verified marketplace listings and auctions
* Marketplace catalog
* Public search
* Global activity feed

Account comments are comments whose topic is the account profile. v1 does not provide a query for every comment authored by an address or for comment replies.

## Read a response

A single resource uses `data`:

```json
{
  "data": {}
}
```

A list also includes pagination:

```json
{
  "data": [],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "opaque-cursor"
  }
}
```

Health is the one envelope exception. It returns `status`, `version`, and `timestamp` directly.

## Paginate results

Chronological streams use opaque cursor pagination with `limit` and `cursor`. Directories, rankings, and current projections use `limit` and `offset`.

The default limit is 50 and the maximum is 100 unless an operation's schema says otherwise. Pass `nextCursor` back exactly as returned. Do not parse or construct cursor values.

## Handle identifiers and numbers

* Ethereum addresses and hashes are lowercase `0x` strings.
* Large blockchain integers are decimal strings.
* Wei fields are decimal strings with names such as `priceWei`.
* API and database timestamps use ISO 8601 UTC.
* Date-only statistics use `YYYY-MM-DD`.

## Handle errors

```json
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 100",
    "requestId": "request-id",
    "details": {}
  }
}
```

Stable codes include `invalid_request`, `invalid_api_key`, `insufficient_scope`, `not_found`, `rate_limit_exceeded`, `internal_error`, and `service_unavailable`.

| Response | What to do |
|---|---|
| `401` or `invalid_api_key` | Send the raw key in `X-API-Key`. Check whether the key was revoked, suspended, or belongs to an account that is no longer eligible. |
| `403` or `insufficient_scope` | Use a key with the scope required by the operation. |
| `429` or `rate_limit_exceeded` | Stop retrying and wait for the rate-limit window. Creating or rotating keys does not increase the owner's quota. |

Keep the `requestId` when reporting an API problem.

## Account for data freshness

The API reads indexed protocol and application data. A confirmed Ethereum transaction may appear later in collection details, activity, comments, listings, auctions, statistics, or search.

Active listing and auction results are returned only after supported-contract and ownership checks. Do not describe v1 results as direct, real-time Ethereum RPC reads.

## Review key usage

Settings shows 30 UTC days of requests, errors, rate-limited requests, last use, and average response time for each key. Recent usage can take a short time to appear.

## v1 limits

v1 does not provide:

* Public write operations
* Real-time subscriptions
* Administrative indexer controls
* Personalized wallet results
* Compatibility guarantees for internal `/gfy` response formats

For complete parameters and schemas, use the [interactive API documentation](https://data.floored.app/gfy/docs).