# Florida Business API — Full Agent Documentation

> Verbose, agent-ingestible documentation. Pure markdown, no JSX. Pair this with the short summary at https://floridabusinessapi.com/llms.txt and the machine-readable OpenAPI at https://floridabusinessapi.com/openapi.json. Source of truth for everything below is https://floridabusinessapi.com/docs.

Florida Business API is an independent data platform and is not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations.

- Base URL: `https://api.floridabusinessapi.com/v1`
- MCP endpoint: `POST https://floridabusinessapi.com/api/mcp` (8 tools)
- Auth: `Authorization: Bearer fbapi_live_…` (or `X-API-Key:` fallback)
- One unified monthly credit bucket funds both REST and MCP (1 credit per request / tool call).

---

## Overview

_Source: https://floridabusinessapi.com/docs/index_

Welcome to the Florida Business API documentation.

Florida Business API is an independent data platform and is not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations. All records are sourced from the public Florida Division of Corporations bulk feed; we mirror, index, and serve them through a stable REST + MCP surface so you do not have to scrape or parse Sunbiz yourself.

## Start Here

- **[Authentication](/docs/authentication)** — Bearer token format, header conventions, key prefixes (`fbapi_live_...` / `fbapi_test_...`), and how to get a key from the [account page](/account).
- **[Errors](/docs/errors)** — Standard error envelope, HTTP status codes, and special codes (`rest_disabled`, JSON-RPC `-32004`).
- **[Rate Limits](/docs/rate-limits)** — Per-tier monthly quotas, requests-per-minute, and the `RateLimit-*` response headers.
- **[Billing](/docs/billing)** — Subscriptions, credit packs, overage billing at $5 per 1K credits, and how to find your balance.
- **[MCP for AI Agents](/docs/mcp)** — Connect Claude, Cursor, or any MCP-compatible agent to live Florida business records (8 tools). MCP is bundled with every paid plan (shared credit bucket); a standalone $5 MCP Starter add-on exists for MCP-only workflows.
- **[Webhooks](/docs/webhooks)** — Webhook delivery format and HMAC signing (planned v2 shape).

## Endpoints

All endpoints live under `https://api.floridabusinessapi.com/v1` (the canonical base URL). If you prefer same-origin requests, the proxy `https://floridabusinessapi.com/api/v1` mirrors the same routes.

### Entities

- **[Search Entities](/docs/endpoints/entities-search)** — `GET /api/v1/entities/search` — fuzzy name + status + entity-type search ranked exact → prefix → trigram similarity.
- **[Get Entity by Document Number](/docs/endpoints/entities-detail)** — `GET /api/v1/entities/{document_number}` — full record including principal/mailing address, registered agent, officers (no PII), and the 50 most-recent filings.

### People & Agents

- **[Search Officers](/docs/endpoints/officers-search)** — `GET /api/v1/officers/search` — officer name + title search across every entity. **Officer addresses are intentionally never returned** (PII gate).
- **[Search Registered Agents](/docs/endpoints/agents-search)** — `GET /api/v1/agents/search` — registered agent search with linked-entity counts. RA business address **is** returned (it is the published commercial address, not PII).
- **[Search Addresses](/docs/endpoints/addresses-search)** — `GET /api/v1/addresses/search` — entities by principal/mailing address.

### Leads & Filings

- **[New-Business Lead Feed](/docs/endpoints/leads-new-businesses)** — `GET /api/v1/leads/new-businesses` — newly-registered businesses filtered by county, city, entity type, and filing-date range. Lead Feed tier subscribers can also fetch the enriched daily CSV.
- **[Daily Filings](/docs/endpoints/filings-daily)** — `GET /api/v1/filings/daily?date=YYYY-MM-DD` — every filing event for a single day.
- **[Recent Filings](/docs/endpoints/filings-recent)** — `GET /api/v1/filings/recent` — filing events across the last N days.

### Account

- **[Account Usage](/docs/endpoints/account-usage)** — `GET /api/v1/account/usage` — current month consumption against your plan quota.

## For AI agents

Building an agent (Claude, ChatGPT, Cursor, custom)? Point it at [`/llms.txt`](/llms.txt) for a ~2 KB one-fetch onboarding summary, or [`/llms-full.txt`](/llms-full.txt) for the verbose ingest-everything version. Both are generated from the canonical `/docs/` source and stay in sync automatically. The machine-readable REST spec lives at [`/openapi.json`](/openapi.json), the plugin manifest at [`/.well-known/ai-plugin.json`](/.well-known/ai-plugin.json), and the MCP transport at [`/api/mcp`](/docs/mcp) (8 tools, same `Authorization: Bearer fbapi_…` header as REST).

## FCRA Disclaimer

Florida Business API data is **not a consumer report** as defined by the Fair Credit Reporting Act (15 U.S.C. § 1681). You may not use it to make decisions about credit, employment, insurance, housing, or any other purpose covered by the FCRA. See [/legal/terms](/legal/terms) for the full acceptable-use policy.

---

## Authentication

_Source: https://floridabusinessapi.com/docs/authentication_

Florida Business API uses API key authentication. Every request to `/api/v1/*` requires a key.

Florida Business API is an independent data platform and is not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations.

## Getting a Key

Create an account and provision a key from the [Account page](/account). Keys are issued instantly and the raw key value is shown **once** at creation time — copy it into your secret store before you close the dialog. We only store an HMAC-SHA256 hash and cannot retrieve it for you.

Live keys count against your plan's monthly credit bucket (unified across REST and MCP — see [Rate Limits](/docs/rate-limits)). Test keys (`fbapi_test_...`) hit the same endpoints with reduced quota and are safe to commit into CI logs.

## Header Format

Send your API key in either header. `Authorization: Bearer` is the preferred convention (matches Stripe, GitHub, Anthropic) and is what we use in every example.

```http
Authorization: Bearer fbapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The `X-API-Key` fallback exists for clients that strip the `Authorization` header (some browser extensions, naive proxies):

```http
X-API-Key: fbapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

> **Querystring auth is not supported.** Passing the key as `?api_key=...` will not authenticate the request and risks leaking the key into server logs, browser history, and HTTP referrers. Always use a header.

If both headers are present **and** they disagree, the request is rejected as `401 unauthorized` — disagreement signals a credential-confusion attack and we will not silently pick one.

## Key Format

Keys follow the pattern `fbapi_{live|test}_{32-char-base62}`.

| Prefix         | Environment | Notes                                                       |
| -------------- | ----------- | ----------------------------------------------------------- |
| `fbapi_live_`  | Production  | Counts against your paid tier's monthly credit bucket.      |
| `fbapi_test_`  | Test        | Same endpoints, reduced quota, safe to commit to CI logs.   |

## Quick Test

```bash
curl -i -H "Authorization: Bearer fbapi_test_..." \
  "https://api.floridabusinessapi.com/v1/entities/search?name=ACME&limit=1"
```

A successful response returns `200` with the standard `{ data, pagination, meta }` envelope plus `X-RateLimit-Remaining` / `X-RateLimit-Reset` headers (see [Rate Limits](/docs/rate-limits)).

## 401 Envelope

Every authentication failure returns the same shape — we do **not** distinguish between "missing key", "revoked key", and "wrong key" so attackers cannot use the API as a key-validity oracle.

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

If you see `unauthorized` repeatedly, double-check that:

1. The header is `Authorization: Bearer <key>` (case-insensitive `Bearer`, single space).
2. You are not stripping the `fbapi_live_` / `fbapi_test_` prefix.
3. You have not revoked the key from the Account page.
4. The client / workspace status is `active` (a suspended workspace returns `401` for every key it owns).

## Storage

Keys are stored as HMAC-SHA256 hashes. The raw key is returned exactly once at creation — store it securely; we cannot retrieve it for you.

## Rotation

Create the new key first, deploy it, then revoke the old one — both can be active in parallel for as long as you need to roll out the change. There is no quota penalty for keeping multiple live keys; each is metered against the same client-level monthly credit bucket.

Revoked keys return `401 unauthorized` immediately on the next request — we enforce `status='active'` AND `revokedAt IS NULL` at the SQL `WHERE` level, so there is no cache window that can serve a stale answer.

---

## Rate Limits + Credits

_Source: https://floridabusinessapi.com/docs/rate-limits_

Florida Business API enforces two limits on every `/api/v1/*` and `/api/mcp` request:

1. **Monthly credit bucket** — one unified pool per customer that funds both REST and MCP. Every request (REST or MCP tool call) decrements the same balance by 1 credit.
2. **Per-minute rate limit (RPM)** — a sliding-window burst limit, by plan.

Whichever you hit first returns `429 rate_limited` with a `Retry-After` header. Both buckets are backed by Upstash Redis with a 1-second timeout that fails open (we'd rather under-bill than 5xx your job).

Florida Business API is an independent data platform and is not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations.

## Tiers

| Plan                 | Monthly Credits (REST + MCP, unified) | RPM (burst) | REST | MCP | CSV | Webhooks |
| -------------------- | ------------------------------------- | ----------- | :--: | :-: | :-: | :------: |
| Free Trial           | 500 at signup, full access 7 days then capped at min(remaining, 100) | 30 |  ✓   |  —  |  —  |    —     |
| Developer ($19/mo)   | 10,000                                | 60          |  ✓   |  ✓  |  —  |    —     |
| Pro ($49/mo)         | 50,000                                | 150         |  ✓   |  ✓  |  ✓  |  beta    |
| Growth ($149/mo)     | 250,000                               | 300         |  ✓   |  ✓  |  ✓  |    ✓     |
| Lead Feed ($299/mo)  | 750,000                               | 600         |  ✓   |  ✓  |  ✓  |    ✓     |
| Enterprise (custom)  | Custom                                | Custom      |  ✓   |  ✓  |  ✓  |    ✓     |
| MCP Starter ($5/mo)  | 1,000 (MCP only)                      | 30          |  —   |  ✓  |  —  |    —     |

REQ-006 (2026-06-28): every paid plan from **Developer** up shares ONE monthly credit pool — one REST call or one MCP tool call both cost 1 credit. **MCP Starter** is the only tier where REST is gated off; REST requests on a Starter key return `403 rest_disabled` (see [Errors](/docs/errors)). The Free Trial gates MCP off (REST-only trial). Enterprise quota is contract-bound; internally it is modeled as a 2,000,000,000-row cap so the Postgres INT column does not overflow.

## Overage billing (paid subscriptions)

As of **2026-06-28**, paid subscription customers (Developer through Lead Feed) no longer hard-stop at quota. Once your monthly grant is exhausted, the API keeps serving `200 OK` and accrues **overage credits** which are billed daily on your next invoice at:

- **$5 per 1,000 credits** ($0.005 per credit)
- Rounded **up** to the nearest **$0.05**

So a single request over quota costs $0.05; 100 requests over quota costs $0.50; 10,000 over costs $50.00. The line item appears as "API Overage" on your normal monthly invoice — no separate charge. See the [Billing doc](/docs/billing#overage) for worked examples.

Overage **does not** apply to:

- **Free trial** clients (those receive `402 Payment Required` instead — upgrade or buy a credit pack to continue)
- **Subscriptions in `past_due` status** (card needs to clear before we resume serving)
- **MCP Starter** subscribers (top up with a credit pack when 1,000 MCP calls are used up)

## Credit packs (one-time, any plan)

If you want a hard ceiling and no monthly commitment, buy a **credit pack**:

| Pack          | Credits  | Price | Per 1K credits |
| ------------- | --------:| -----:| --------------:|
| Starter       |    1,000 |  $5   | $5.00          |
| Investigator  |    5,000 | $23   | $4.60          |
| Bulk          |   25,000 | $99   | $3.96          |
| Power         |  100,000 | $349  | $3.49          |

Pack credits **expire 12 months after purchase**. Within a billing cycle, monthly plan credits are consumed **first** — pack credits only burn once your monthly bucket is empty. Pack credits do **not** unlock plan-gated features (CSV exports, webhooks) and do **not** raise your per-minute rate limit; those follow the plan you are on. See the [Billing doc](/docs/billing#credit-packs) for the purchase flow.

The **Free** tier is a **7-day trial**: each new client is granted 500 credits at signup. For the first 7 days you have full access to whatever balance remains. On the first API call after day 7, your balance is automatically capped at `min(remaining_balance, 100)` — a one-shot adjustment recorded in the credit ledger as `free_trial_expired_cap`. After that, when the remaining credits run out the API returns `402 Payment Required` with an upgrade hint pointing at [/pricing](/pricing). Upgrading to any paid tier removes the cap and swaps the gate to the recurring monthly grant.

## Response Headers

Every `/api/v1/*` response (including `429`) includes both the legacy de-facto headers and the IETF draft `RateLimit` structured field — pick whichever your HTTP client supports:

| Header                | Meaning                                                                |
| --------------------- | ---------------------------------------------------------------------- |
| `X-RateLimit-Limit`   | Your plan's RPM cap.                                                   |
| `X-RateLimit-Remaining` | Requests remaining in the current 60-second window.                  |
| `X-RateLimit-Reset`   | Unix seconds at which the window resets.                               |
| `RateLimit`           | RFC 9651 structured field: `"default";r=<remaining>;t=<seconds_until_reset>`. |
| `Retry-After`         | **Only on 429.** Seconds until you may retry.                          |

Example success headers:

```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1719367200
RateLimit: "default";r=57;t=42
```

## 429 Envelope

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 17
RateLimit: "default";r=0;t=17
```

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 17 seconds.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

## Handling 429s

The simplest correct strategy: sleep `Retry-After` seconds, then retry once.

```bash
while :; do
  RESP=$(curl -s -w "\n%{http_code}" \
    -H "Authorization: Bearer fbapi_live_..." \
    "https://api.floridabusinessapi.com/v1/entities/search?name=ACME")
  CODE=$(printf '%s\n' "$RESP" | tail -n1)
  BODY=$(printf '%s\n' "$RESP" | sed '$d')
  [ "$CODE" = "200" ] && { echo "$BODY"; break; }
  [ "$CODE" = "429" ] && { sleep "${Retry_After:-30}"; continue; }
  echo "fatal: $CODE — $BODY" >&2; exit 1
done
```

For long-running batch jobs, use exponential backoff capped at the `X-RateLimit-Reset` value — you will never wait longer than the window itself.

## Monthly Quota vs. RPM

- Hitting **RPM** returns 429 and resets within ~60 seconds. Slow down and you can finish your job today.
- Hitting **monthly quota** also returns 429, but `Retry-After` will be the seconds until your next billing cycle. Upgrade or wait — there is no in-cycle escape hatch.

Check current consumption from the [Account Usage endpoint](/docs/endpoints/account-usage).

---

## Billing

_Source: https://floridabusinessapi.com/docs/billing_

The Florida Business API offers **two ways to pay** — pick what fits your usage.

| Model         | Best for                                  | What you pay                          |
| ------------- | ----------------------------------------- | ------------------------------------- |
| Subscription  | Recurring usage, production integrations  | Fixed monthly fee + overage           |
| Credit pack   | Journalists, researchers, one-off bulk    | One-time charge, no commitment        |

You can mix both — credit packs work on any plan, including Free.

## Subscriptions

Subscriptions are billed monthly via Stripe. Each plan grants a single unified monthly credit bucket that funds both REST and MCP — there is no separate "MCP calls" budget on Developer and above. As of REQ-006 (2026-06-28):

| Plan                 | Price     | Credits / mo  |
| -------------------- | --------- | -------------:|
| Free Trial           | $0        | 500 one-time  |
| Developer            | $19 / mo  | 10,000        |
| Pro                  | $49 / mo  | 50,000        |
| Growth               | $149 / mo | 250,000       |
| Lead Feed            | $299 / mo | 750,000       |
| Enterprise           | Custom    | Custom        |
| MCP Starter (MCP-only add-on) | $5 / mo | 1,000 |

Monthly plan credits **do not roll over** between cycles — at the start of each cycle the new grant lands and any unused credits from the prior cycle are dropped. If you need a buffer that persists across cycles, buy a [credit pack](#credit-packs). See the [Pricing page](/pricing) for the full feature breakdown per tier.

### Overage

If you blow past the monthly grant on a paid subscription, the API **does not hard-stop**. Each request past the quota is recorded as an overage credit and you keep getting `200 OK` responses. Overage is billed at:

- **$5 per 1,000 credits** ($0.005 per credit)
- Rounded **up** to the nearest **$0.05**

Examples:

| Overage credits | Billed amount |
| --------------- | ------------- |
| 1               | $0.05         |
| 100             | $0.50         |
| 1,000           | $5.00         |
| 1,001           | $5.05         |
| 10,000          | $50.00        |

Overage is billed **daily** at **01:00 UTC** via a one-shot line item on your next subscription invoice — not as a separate charge. If you cancel before your next invoice, what's accrued is still billed on the final invoice.

### Quota resets

The monthly quota resets at the start of each billing cycle. The Free trial is the only plan with a one-shot quota cap (after 7 days your balance drops to `min(remaining, 100)` once); see [Rate Limits](/docs/rate-limits) for trial mechanics.

## Credit packs

Credit packs are one-time purchases. Credits **never expire** and work on every plan tier.

| Pack          | Credits  | Price | Per 1K credits |
| ------------- | --------:| -----:| --------------:|
| Starter       |    1,000 |  $5   | $5.00          |
| Investigator  |    5,000 | $23   | $4.60          |
| Bulk          |   25,000 | $99   | $3.96          |
| Power         |  100,000 | $349  | $3.49          |

Use a credit pack when you want to:

- Pull data for a one-off story without committing to a plan
- Add a buffer to a Free-tier account
- Top up a paid subscription mid-cycle without changing your plan

### Pack rules (REQ-006)

Three rules pin the difference between plan credits and pack credits:

1. **Pack credits expire 12 months after purchase.** A Power Pack bought on 2026-06-28 expires on 2027-06-28 at 00:00 UTC. Expired pack credits are dropped from your balance — they are not refunded.
2. **Monthly plan credits are consumed first within a billing cycle.** Pack credits only start burning after the monthly bucket hits zero. Buying a pack mid-cycle is never wasted — your unused monthly credits get used first, then the pack picks up. Monthly plan credits do **not** roll over at the end of the billing cycle.
3. **Pack credits do not unlock plan-gated features.** CSV exports stay locked on the Developer plan even if you add a Bulk Pack. The per-minute rate limit also follows your plan, not your pack.

### Buying a credit pack

Open the [Pricing page](/pricing) while signed in and click the pack you want. You'll be redirected to Stripe Checkout. After payment, credits land in your balance within a few seconds (when the Stripe webhook reaches our server).

If you'd rather call the API directly:

```bash
curl -X POST https://floridabusinessapi.com/api/v1/billing/checkout-credit-pack \
  -H "X-API-Key: $FBAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"investigator"}'
```

The response is `{ "data": { "url": "https://checkout.stripe.com/c/pay/cs_..." } }`. Open that URL in a browser to complete the purchase.

Valid `slug` values are `starter`, `investigator`, `bulk`, and `power`.

## Where to find your balance

Your current credit balance and any accrued overage are exposed on the [account dashboard](/account) and via the API:

```bash
curl -H "X-API-Key: $FBAPI_KEY" \
  https://floridabusinessapi.com/api/v1/account/usage
```

The response includes monthly REST event count, your plan's quota, and the reset date. For the canonical balance number (which credits all consumption — REST, MCP, overage, grants, and packs — into a single signed integer), call:

```bash
curl -H "X-API-Key: $FBAPI_KEY" \
  https://floridabusinessapi.com/api/v1/billing/balance
```

## How to upgrade / buy a pack

- **Upgrade subscription**: [Pricing page](/pricing) → pick a tier → "Get started".
- **Switch tier mid-cycle**: from your [account billing page](/account/billing). Upgrades prorate immediately; downgrades take effect at the end of the cycle.
- **Buy a credit pack**: [Pricing page](/pricing) → scroll to "Credit packs" → "Buy now — no subscription".
- **Cancel a subscription**: from your account billing page. Cancellation takes effect at the end of the current cycle; you keep your credits and any unbilled overage rolls into the final invoice.

## Refunds and disputes

We don't issue partial refunds for unused subscription credits. Credit pack purchases are refundable within 14 days **provided no more than 10% of the pack has been consumed**. Email [billing@floridabusinessapi.com](mailto:billing@floridabusinessapi.com) with your Stripe receipt to start a refund.

If you suspect a billing error or unauthorized charge, contact us first — Stripe disputes blackout further purchases for 60 days while the dispute settles.

## Tax

Florida Business API is a Florida LLC. Sales tax is **not** added to subscriptions or credit packs at this time; we'll notify you in advance if that changes.

---

## MCP — Florida Business API for AI Agents

_Source: https://floridabusinessapi.com/docs/mcp_

# Florida Business API — Model Context Protocol

Florida Business API ships a Model Context Protocol (MCP) server so AI coding agents and copilots can search Florida business records directly, without you scraping or writing custom integrations.

Florida Business API is an independent data platform and is not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations.

## What is MCP

MCP is an open transport for connecting LLM agents to live tools and data sources. Once installed, your agent gains 8 new tools that hit Florida Business API on your behalf — same data as `/api/v1`, same auth key, but invoked by the model.

## Connection

| Setting     | Value                                          |
| ----------- | ---------------------------------------------- |
| Endpoint    | `https://floridabusinessapi.com/api/mcp`           |
| Transport   | HTTP streaming (MCP 2025-06-18+)               |
| Auth header | `Authorization: Bearer fbapi_live_...`         |
| Plan needed | Any plan with `mcp` in `surfaces` (all tiers)  |

Every paid plan from **Developer** ($19/mo) up includes MCP access. As of REQ-006 (2026-06-28), MCP calls draw from the **same** monthly credit bucket as REST — there is no separate "MCP calls" budget. One MCP tool call costs 1 credit; one REST request costs 1 credit; both decrement the same balance.

If you only need MCP and don't care about REST, the standalone **$5 MCP Starter** add-on gives you 1,000 MCP credits / month with no REST surface. REST requests on a Starter key return `403 rest_disabled`.

## Install

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "florida-business-api": {
      "transport": "http",
      "url": "https://floridabusinessapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer fbapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Restart Claude Desktop. The 8 tools appear under the slider icon in the prompt bar.

### Claude Code

```bash
claude mcp add florida-business-api \
  --transport http \
  --url https://floridabusinessapi.com/api/mcp \
  --header "Authorization: Bearer fbapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Run `claude mcp list` to confirm. New tools are namespaced `mcp__florida-business-api__<tool>`.

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "florida-business-api": {
      "url": "https://floridabusinessapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer fbapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### OpenClaw / Hermes

Add to your gateway config (e.g. `~/.claude/mcp.json` or the Hermes profile MCP block):

```json
{
  "florida-business-api": {
    "type": "http",
    "url": "https://floridabusinessapi.com/api/mcp",
    "headers": {
      "Authorization": "Bearer fbapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
```

Restart the gateway. Tools route through the standard MCP envelope.

## Tools

| Tool                           | What it does                                                        | Example prompt                                                                |
| ------------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `search_entities`              | Fuzzy-search FL business entities by name/status/type.              | "Find every active LLC in Florida whose name starts with 'Coastal'."          |
| `get_entity`                   | Fetch full entity detail by document number.                        | "Pull the full record for document L26000123456."                             |
| `search_officers`              | Search officers/principals across all FL entities.                  | "Which Florida companies list 'John Smith' as an officer?"                    |
| `search_agents`                | Search registered agents.                                           | "Show me entities using 'Northwest Registered Agent' in FL."                  |
| `search_addresses`             | Reverse-lookup entities by address or ZIP.                          | "What companies are registered at 33602?"                                     |
| `list_daily_filings`           | Today's (or any date's) new business filings.                       | "List every business filed in Florida yesterday."                             |
| `list_recent_filings`          | Filings from the last N days.                                       | "Give me Florida LLC filings from the past 7 days."                           |
| `list_new_business_leads`      | Filtered lead-feed: county + city + entity_type + date_from.        | "Pull new LLCs filed in Hillsborough County, Tampa, this month."              |

Each tool returns the same JSON shape as the corresponding REST endpoint at `/api/v1/*`, so agent-built workflows can graduate to direct REST integration without changing data contracts.

## Account & Credits

MCP calls draw from the **same monthly credit bucket** as REST API calls — one unified balance per customer. Every tool invocation costs 1 credit, just like a `GET /api/v1/...` request. Check your remaining budget any time:

```
GET /api/v1/account/usage
```

Top up or change plans at [/account/billing](https://floridabusinessapi.com/account/billing). The standalone **MCP Starter** plan ($5/mo, 1,000 credits) is MCP-only and does **not** include REST access — every other plan (Developer and above) includes both MCP and REST under the same bucket.

## Worked Examples

Try these in a chat after install:

1. **Lead generation.** "Pull all new Florida LLC filings in Hillsborough County for the last 14 days, then group them by city."
2. **KYB lookup.** "Look up document number P26000045678 and tell me the officers, registered agent, and principal address."
3. **Officer cross-reference.** "Find every Florida company that lists 'Jane Doe' as an officer and summarize their entity types."
4. **Address sweep.** "Which businesses are registered at addresses in the 33602 ZIP code?"
5. **Daily intake.** "Give me yesterday's new business filings in Florida and save the list as a CSV."

## Errors

- `403 rest_disabled` — your plan is MCP-only (likely MCP Starter); hit `/api/mcp` instead of `/api/v1`, or upgrade.
- `403 mcp_disabled` — your plan has no MCP access; upgrade to any tier ≥ Free.
- `429 rate_limited` — monthly credit bucket exhausted (unified across MCP + REST), or per-minute burst cap hit; top up or wait until reset.

See [Errors](/docs/errors) for the full error envelope.

---

## Errors

_Source: https://floridabusinessapi.com/docs/errors_

All Florida Business API errors return a uniform JSON envelope. The shape is identical across REST endpoints; the MCP server wraps the same `code` / `message` inside a JSON-RPC error.

Florida Business API is an independent data platform and is not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations.

## REST Envelope

```json
{
  "error": {
    "code": "bad_request",
    "message": "Human-readable description of what went wrong.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

Every response — success or failure — includes a `request_id`. Quote it when filing support tickets so we can pull the matching server log.

## Codes

| Code              | HTTP  | Meaning                                                                                |
| ----------------- | ----- | -------------------------------------------------------------------------------------- |
| `bad_request`     | 400   | Query params failed validation.                                                        |
| `unauthorized`    | 401   | Missing, invalid, or revoked API key. See [Authentication](/docs/authentication).      |
| `payment_required`| 402   | Workspace credit balance is empty and auto-topup is disabled.                          |
| `forbidden`       | 403   | Authenticated but not permitted for this resource (e.g. MCP-only tier hitting REST).   |
| `rest_disabled`   | 403   | Your plan's `surfaces` array does not include `rest` — see below.                      |
| `not_found`       | 404   | Resource does not exist.                                                               |
| `rate_limited`    | 429   | Per-key RPM or monthly quota exceeded. `Retry-After` header included.                  |
| `internal_error`  | 5xx   | Server-side failure. Reference `request_id` in support tickets.                        |

## 400 `bad_request`

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
```

```json
{
  "error": {
    "code": "bad_request",
    "message": "limit must be between 1 and 500.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

## 401 `unauthorized`

Same shape for missing / invalid / revoked / wrong-workspace keys (no oracle):

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

## 402 `payment_required`

Returned when a metered request needs to draw credits and the workspace balance is empty with auto-topup off.

```json
{
  "error": {
    "code": "payment_required",
    "message": "Credit balance is zero. Enable auto-topup or purchase a credit pack.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

## 403 `rest_disabled`

The **MCP Starter** tier ($5/mo, 1,000 MCP calls) does not include the `/api/v1/*` REST surface. The key authenticates correctly, but the REST router rejects the request:

```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
```

```json
{
  "error": {
    "code": "rest_disabled",
    "message": "This plan does not include REST API access. Use the MCP transport or upgrade to a tier that includes REST.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

Upgrade to **Developer** or higher to add `rest` to your plan's `surfaces`.

## 404 `not_found`

```json
{
  "error": {
    "code": "not_found",
    "message": "Entity L00000000000 not found.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

## 429 `rate_limited`

Sent when you exceed either the per-minute rate limit or the monthly quota. The `Retry-After` header tells you when to retry (seconds).

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 17
```

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 17 seconds.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

See [Rate Limits](/docs/rate-limits) for per-tier limits.

## 5xx `internal_error`

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "req_1234567890abcdef12345"
  }
}
```

Retry with exponential backoff. If the same `request_id` reproduces consistently, open a support ticket with the ID — we keep request-scoped logs for 30 days.

## MCP / JSON-RPC Errors

The MCP server at `/api/mcp` wraps the same condition set inside a JSON-RPC 2.0 error frame. Codes:

| JSON-RPC Code | Meaning                                                                                |
| ------------- | -------------------------------------------------------------------------------------- |
| `-32600`      | Invalid Request — malformed JSON-RPC envelope.                                         |
| `-32601`      | Method not found — tool name does not exist.                                           |
| `-32602`      | Invalid params — tool argument validation failed (mirrors REST `bad_request`).         |
| `-32603`      | Internal error — mirrors REST `internal_error`.                                        |
| `-32001`      | Unauthorized — mirrors REST `unauthorized`.                                            |
| `-32004`      | **Out of credits** — workspace credit balance is zero (mirrors REST `payment_required`).|
| `-32029`      | Rate limited — mirrors REST `rate_limited`. Retry-after seconds in `data.retry_after`. |

Example out-of-credits response:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32004,
    "message": "Out of credits. Enable auto-topup or purchase a credit pack.",
    "data": {
      "request_id": "req_1234567890abcdef12345",
      "credit_balance": 0
    }
  }
}
```

---

## Webhooks

_Source: https://floridabusinessapi.com/docs/webhooks_

> Webhook delivery is a v2 feature. This page documents the planned shape so integrators can prepare. Live delivery, retries, and the admin dashboard ship after the first paying webhook customer requests them.

Florida Business API is an independent data platform and is not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations.

## Planned Shape

Webhooks deliver JSON POST requests to your registered endpoint with an `X-FBA-Signature` header containing an HMAC-SHA256 signature of the raw body using your endpoint's shared secret.

Subscribed event types (planned): `entity.created`, `entity.updated`, `saved_search.match`.

Subscribe via the `/admin/webhooks` interface (admin-only in v1).

---

## Endpoint: Search Entities

_Source: https://floridabusinessapi.com/docs/endpoints/entities-search_

`GET /api/v1/entities/search`

Search Florida business entities by name (fuzzy match via pg_trgm), status, or entity type. Results are ranked: exact name match (1.0) > prefix match (0.9) > trigram similarity > recent filings as the secondary sort key.

## Authentication

Send your API key in the `X-API-Key` header.

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/entities/search?name=ACME&limit=10"
```

## Query Parameters

| Name          | Type                          | Required | Default | Description                                                          |
| ------------- | ----------------------------- | -------- | ------- | -------------------------------------------------------------------- |
| `name`        | string (1-200 chars)          | no       | —       | Entity name (case-insensitive fuzzy match).                          |
| `status`      | enum (`active`, `inactive`)   | no       | —       | Filter by registration status.                                       |
| `entity_type` | string (1-20 chars)           | no       | —       | FL entity type code, e.g. `FLAL`. **Send UPPERCASE** (Pitfall 4-G).  |
| `limit`       | integer 1-500                 | no       | `25`    | Page size.                                                           |
| `offset`      | integer ≥ 0                   | no       | `0`     | Pagination offset.                                                   |

## Response (200)

List envelope `{ data: EntityHit[], pagination, meta }`. Example:

```json
{
  "data": [
    {
      "document_number": "L26000123456",
      "entity_name": "ACME LOGISTICS LLC",
      "status": "active",
      "entity_type": "FLAL",
      "filing_date": "2026-06-24",
      "principal_city": "TAMPA",
      "principal_state": "FL",
      "principal_zip": "33602"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

The runtime response shape is validated against the live Zod schema in [`tests/integration/docs-examples.test.ts`](https://github.com/crogers2287/floridabusinessapi/blob/main/tests/integration/docs-examples.test.ts) — drift fails CI.

## Error Responses

| Status | Code            | Cause                                      |
| ------ | --------------- | ------------------------------------------ |
| `400`  | `bad_request`   | Invalid query parameters.                  |
| `401`  | `unauthorized`  | Missing or invalid API key.                |
| `429`  | `rate_limited`  | Quota or rate limit exceeded.              |
| `500`  | `internal_error`| Server error — retry with backoff.         |

Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers.

---

## Endpoint: Get Entity

_Source: https://floridabusinessapi.com/docs/endpoints/entities-detail_

`GET /api/v1/entities/{document_number}`

Returns full detail for a single Florida business entity. The response includes the principal and mailing addresses, registered agent (with their address), officers (name + title only — addresses are NOT returned per Pitfall 4-H PII gate), and the 50 most-recent filing events.

## Authentication

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/entities/L23000038085"
```

## Path Parameters

| Name              | Type                       | Required | Description                                              |
| ----------------- | -------------------------- | -------- | -------------------------------------------------------- |
| `document_number` | string (6-12 alphanumeric) | yes      | FL Division of Corporations document number.             |

## Response (200)

Single-object envelope `{ data: EntityDetail, meta }`. Example:

```json
{
  "data": {
    "document_number": "L23000038085",
    "entity_name": "WALT DISNEY TRAVEL CO., LLC",
    "status": "active",
    "entity_type": "FLAL",
    "filing_date": "2023-01-24",
    "principal_address": { "line1": "1375 BUENA VISTA DR", "city": "LAKE BUENA VISTA", "state": "FL", "postal_code": "32830" },
    "mailing_address":   { "line1": "1375 BUENA VISTA DR", "city": "LAKE BUENA VISTA", "state": "FL", "postal_code": "32830" },
    "registered_agent":  { "name": "CORPORATION SERVICE COMPANY", "address": { "line1": "1201 HAYS STREET", "city": "TALLAHASSEE", "state": "FL", "postal_code": "32301" } },
    "officers": [ { "name": "DOE, JANE", "title": "MGR" } ],
    "recent_filings": [ { "event_type": "FORMATION", "event_date": "2023-01-24", "document_number": "L23000038085", "description": "Articles of Organization" } ]
  },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

Officers carry only `{ name, title }` — never `address`. Officer addresses are considered PII and are gated at three layers (Zod response schema, route handler shaping, and a per-officer key-equality test in `src/lib/search/__tests__/`).

## Error Responses

| Status | Code            | Cause                                |
| ------ | --------------- | ------------------------------------ |
| `400`  | `bad_request`   | Invalid document_number format.      |
| `401`  | `unauthorized`  | Missing or invalid API key.          |
| `404`  | `not_found`     | No entity with that document_number. |
| `429`  | `rate_limited`  | Quota or rate limit exceeded.        |
| `500`  | `internal_error`| Server error — retry with backoff.   |

---

## Endpoint: Search Officers

_Source: https://floridabusinessapi.com/docs/endpoints/officers-search_

`GET /api/v1/officers/search`

Search Florida business officers by name (fuzzy via pg_trgm) and title across all entities. Returns the officer name, title code, and the linked entity's document number + name. Officer addresses are **never** returned (Pitfall 4-H PII gate).

## Authentication

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/officers/search?name=SMITH&title=MGR&limit=25"
```

## Query Parameters

| Name     | Type                  | Required | Default | Description                                     |
| -------- | --------------------- | -------- | ------- | ----------------------------------------------- |
| `name`   | string (1-200 chars)  | no       | —       | Officer name (case-insensitive fuzzy match).    |
| `title`  | string (1-20 chars)   | no       | —       | Title code, e.g. `MGR`, `DIR` (case-insensitive). |
| `limit`  | integer 1-500         | no       | `25`    | Page size.                                      |
| `offset` | integer ≥ 0           | no       | `0`     | Pagination offset.                              |

## Response (200)

```json
{
  "data": [
    {
      "officer_name": "JANE DOE",
      "title_code": "MGR",
      "document_number": "L26000123456",
      "entity_name": "ACME LOGISTICS LLC"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

## Error Responses

| Status | Code            | Cause                              |
| ------ | --------------- | ---------------------------------- |
| `400`  | `bad_request`   | Invalid query parameters.          |
| `401`  | `unauthorized`  | Missing or invalid API key.        |
| `429`  | `rate_limited`  | Quota or rate limit exceeded.      |
| `500`  | `internal_error`| Server error — retry with backoff. |

---

## Endpoint: Search Registered Agents

_Source: https://floridabusinessapi.com/docs/endpoints/agents-search_

`GET /api/v1/agents/search`

Search Florida registered agents by name (fuzzy via pg_trgm). Each result row aggregates: the agent's identity (`name`), the count of currently-linked entities (`linked_entity_count`), and the agent's primary mailing address.

## Authentication

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/agents/search?name=SMITH&limit=25"
```

## Query Parameters

| Name     | Type                  | Required | Default | Description                                  |
| -------- | --------------------- | -------- | ------- | -------------------------------------------- |
| `name`   | string (1-200 chars)  | no       | —       | Agent name (case-insensitive fuzzy match).   |
| `limit`  | integer 1-500         | no       | `25`    | Page size.                                   |
| `offset` | integer ≥ 0           | no       | `0`     | Pagination offset.                           |

## Response (200)

```json
{
  "data": [
    {
      "agent_name": "JOHN SMITH",
      "linked_entity_count": 128,
      "city": "TAMPA",
      "state": "FL",
      "zip": "33602"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

Results are ranked by exact > prefix > trigram similarity (primary), then by `linked_entity_count DESC` (secondary), then by `agent_name ASC`.

## Error Responses

| Status | Code            | Cause                              |
| ------ | --------------- | ---------------------------------- |
| `400`  | `bad_request`   | Invalid query parameters.          |
| `401`  | `unauthorized`  | Missing or invalid API key.        |
| `429`  | `rate_limited`  | Quota or rate limit exceeded.      |
| `500`  | `internal_error`| Server error — retry with backoff. |

---

## Endpoint: Search Addresses

_Source: https://floridabusinessapi.com/docs/endpoints/addresses-search_

`GET /api/v1/addresses/search`

Search Florida business addresses with a single `query` parameter that accepts a street, a city, or a ZIP code. If the query matches `\d{5}` or `\d{5}-\d{4}` the route takes a fast equality branch on `Address.postalCode`; otherwise it runs trigram fuzzy match against the normalized address.

## Authentication

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/addresses/search?query=33602&limit=25"
```

## Query Parameters

| Name     | Type                  | Required | Default | Description                                                      |
| -------- | --------------------- | -------- | ------- | ---------------------------------------------------------------- |
| `query`  | string (1-200 chars)  | no       | —       | Street, city, ZIP5, or ZIP+4. ZIP-looking input takes fast path. |
| `limit`  | integer 1-500         | no       | `25`    | Page size.                                                       |
| `offset` | integer ≥ 0           | no       | `0`     | Pagination offset.                                               |

## Response (200)

```json
{
  "data": [
    {
      "address": "123 MAIN ST",
      "city": "TAMPA",
      "state": "FL",
      "zip": "33602",
      "document_number": "L26000123456",
      "entity_name": "ACME LOGISTICS LLC"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

Each row is one (address, linked entity) pair — a single physical address with N principal-address entities will appear N times.

## Error Responses

| Status | Code            | Cause                              |
| ------ | --------------- | ---------------------------------- |
| `400`  | `bad_request`   | Invalid query parameters.          |
| `401`  | `unauthorized`  | Missing or invalid API key.        |
| `429`  | `rate_limited`  | Quota or rate limit exceeded.      |
| `500`  | `internal_error`| Server error — retry with backoff. |

---

## Endpoint: Daily Filings

_Source: https://floridabusinessapi.com/docs/endpoints/filings-daily_

`GET /api/v1/filings/daily`

List entities filed on a specific date. Backed by the `DailyFiling` table (one row per record per file) populated by the Phase 5 importer. Without a `date` parameter the route returns the most-recent ingested filings.

## Authentication

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/filings/daily?date=2026-06-24&limit=25"
```

## Query Parameters

| Name     | Type                     | Required | Default | Description                                                 |
| -------- | ------------------------ | -------- | ------- | ----------------------------------------------------------- |
| `date`   | string `YYYY-MM-DD`      | no       | —       | UTC calendar date. Half-open range `[date, date + 1day)`.  |
| `limit`  | integer 1-500            | no       | `25`    | Page size.                                                  |
| `offset` | integer ≥ 0              | no       | `0`     | Pagination offset.                                          |

## Response (200)

```json
{
  "data": [
    {
      "document_number": "L26000123456",
      "entity_name": "ACME LOGISTICS LLC",
      "entity_type": "FLAL",
      "filing_type": "FORMATION",
      "filing_date": "2026-06-24",
      "status": "active"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

## Error Responses

| Status | Code            | Cause                              |
| ------ | --------------- | ---------------------------------- |
| `400`  | `bad_request`   | Invalid date format (use `YYYY-MM-DD`). |
| `401`  | `unauthorized`  | Missing or invalid API key.        |
| `429`  | `rate_limited`  | Quota or rate limit exceeded.      |
| `500`  | `internal_error`| Server error — retry with backoff. |

---

## Endpoint: Recent Filings

_Source: https://floridabusinessapi.com/docs/endpoints/filings-recent_

`GET /api/v1/filings/recent`

List entities filed within the last `days` days (default 7, max 90). Useful for periodically polling for new filings — for larger time windows the bulk export (Phase 6+) is the right tool.

## Authentication

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/filings/recent?days=30&limit=100"
```

## Query Parameters

| Name     | Type            | Required | Default | Description                                       |
| -------- | --------------- | -------- | ------- | ------------------------------------------------- |
| `days`   | integer 1-90    | no       | `7`     | Days back from `now()`. Hard-capped at 90.        |
| `limit`  | integer 1-500   | no       | `25`    | Page size.                                        |
| `offset` | integer ≥ 0     | no       | `0`     | Pagination offset.                                |

## Response (200)

```json
{
  "data": [
    {
      "document_number": "L26000123456",
      "entity_name": "ACME LOGISTICS LLC",
      "entity_type": "FLAL",
      "filing_type": "FORMATION",
      "filing_date": "2026-06-24",
      "status": "active"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

## Error Responses

| Status | Code            | Cause                                  |
| ------ | --------------- | -------------------------------------- |
| `400`  | `bad_request`   | `days > 90` or invalid query parameter. |
| `401`  | `unauthorized`  | Missing or invalid API key.            |
| `429`  | `rate_limited`  | Quota or rate limit exceeded.          |
| `500`  | `internal_error`| Server error — retry with backoff.     |

---

## Endpoint: New-Business Lead Feed

_Source: https://floridabusinessapi.com/docs/endpoints/leads-new-businesses_

`GET /api/v1/leads/new-businesses`

Lead Feed tier endpoint. Returns newly-registered Florida businesses filtered by county (FL only), city, entity type, and filing date range. The county filter uses a dual branch: fast equality on `Address.county` when that column is populated, with a ZIP-set fallback (`Address.postalCode = ANY($zips)`) for rows where county is NULL.

## Authentication

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/leads/new-businesses?county=Hillsborough&entity_type=FLAL&date_from=2026-06-01&limit=100"
```

## Query Parameters

| Name          | Type                   | Required | Default | Description                                                          |
| ------------- | ---------------------- | -------- | ------- | -------------------------------------------------------------------- |
| `county`      | string (max 40 chars)  | no       | —       | FL county name (case-insensitive; "County" suffix stripped).         |
| `city`        | string (max 60 chars)  | no       | —       | City name (case-insensitive).                                        |
| `entity_type` | string (max 20 chars)  | no       | —       | FL entity type code, e.g. `FLAL`. **Send UPPERCASE**.                |
| `date_from`   | string `YYYY-MM-DD`    | no       | —       | Inclusive lower bound on filing date.                                |
| `date_to`     | string `YYYY-MM-DD`    | no       | —       | Inclusive upper bound on filing date (half-open: `< date_to + 1d`).  |
| `limit`       | integer 1-500          | no       | `25`    | Page size.                                                           |
| `offset`      | integer ≥ 0            | no       | `0`     | Pagination offset.                                                   |

## Response (200)

```json
{
  "data": [
    {
      "document_number": "L26000123456",
      "entity_name": "ACME LOGISTICS LLC",
      "entity_type": "FLAL",
      "filing_date": "2026-06-24",
      "city": "TAMPA",
      "state": "FL",
      "zip": "33602",
      "county": "Hillsborough"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1, "has_more": false },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

Sorted by `filing_date DESC` (most recent first), then `document_number ASC` for stable pagination.

## Error Responses

| Status | Code            | Cause                                  |
| ------ | --------------- | -------------------------------------- |
| `400`  | `bad_request`   | Invalid query parameters / date format.|
| `401`  | `unauthorized`  | Missing or invalid API key.            |
| `429`  | `rate_limited`  | Quota or rate limit exceeded.          |
| `500`  | `internal_error`| Server error — retry with backoff.     |

---

## Endpoint: Account Usage

_Source: https://floridabusinessapi.com/docs/endpoints/account-usage_

`GET /api/v1/account/usage`

Returns the calling key's current calendar-month usage. Useful for client-side dashboards, quota warning banners, and pre-flight rate-limit budgeting.

## Authentication

```bash
curl -H "X-API-Key: fbapi_live_..." \
  "https://api.floridabusinessapi.com/v1/account/usage"
```

## Query Parameters

None.

## Response (200)

```json
{
  "data": {
    "events_count": 1247,
    "monthly_quota": 10000,
    "percent_used": 12.47,
    "reset_date": "2026-07-01T00:00:00.000Z",
    "plan": "pro"
  },
  "meta": { "request_id": "req_1234567890abcdef12345" }
}
```

| Field           | Type                | Description                                                           |
| --------------- | ------------------- | --------------------------------------------------------------------- |
| `events_count`  | integer             | Successful API-usage events counted this calendar month (UTC).        |
| `monthly_quota` | integer             | The key's monthly quota (per plan tier).                              |
| `percent_used`  | number (2 decimals) | `events_count / monthly_quota * 100`. Zero when quota is unlimited.   |
| `reset_date`    | ISO 8601 timestamp  | UTC start of next calendar month (when the counter resets).           |
| `plan`          | string              | Plan tier (e.g. `free`, `pro`, `enterprise`).                         |

## Error Responses

| Status | Code            | Cause                              |
| ------ | --------------- | ---------------------------------- |
| `401`  | `unauthorized`  | Missing or invalid API key.        |
| `429`  | `rate_limited`  | Rate limit exceeded.               |
| `500`  | `internal_error`| Server error — retry with backoff. |

---

## Contact + Links

- Pricing: https://floridabusinessapi.com/pricing
- Account / API keys: https://floridabusinessapi.com/account
- Public search (no key): https://floridabusinessapi.com/search
- Dataset status (JSON): https://floridabusinessapi.com/api/public/dataset-status
- Status + uptime: https://floridabusinessapi.com/status
- Support: support@floridabusinessapi.com
- Terms: https://floridabusinessapi.com/legal/terms
- Privacy: https://floridabusinessapi.com/legal/privacy
- FCRA notice: https://floridabusinessapi.com/legal/fcra-notice