> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formo.so/llms.txt
> Use this file to discover all available pages before exploring further.
# API overview
> Explore the Formo API suite including the Events API for data ingestion, Query API for SQL analytics, and Profiles API for wallet data and personalization.
## Events API
* Send individual or batches of events via `events.formo.so` to Formo.
* High-throughput streaming ingestion with an easy-to-use HTTP API.
* Supports 1000 requests/s and 20MB/s.
## Profiles API
You can use the Profiles API for real-time personalization. Once you fetch a profile, you can use them in your app for real-time personalization.
* Fetch wallet profile properties including net worth and wallet labels
* Segment and target users based on location, device, and referrer
* Real-time activation API for personalized user experiences
* Also accessible by AI agents via [x402](https://www.x402.org/) (`formo.x402.paysponge.com`) and [MPP](https://mpp.dev/) (`formo.mpp.paysponge.com`) — pay per request, no API key required
## Query API
* Connect BI tools and SQL clients via [BI integration](/data/bi).
* Query and filter raw analytics events, materialized views, and metrics.
* Return the activity feed / event stream for an anonymous visitor or wallet.
* Export data periodically to your data warehouse.
## Charts API
* Create and manage custom dashboards and charts.
* Add, update, and remove charts with SQL-based queries and visualization options (bar, line, pie, funnel, stacked, retention, and more).
## Segments API
* Create and manage user segments based on filter conditions.
* Segment users by DeFi positions, net worth, transaction count, device, browser, lifetime volume, and other attributes.
## Contracts API
* Monitor blockchain smart contract events across all major chains.
* Add contracts by chain ID, address, and ABI to get fully-decoded transaction and smart contract events.
## Alerts API
* Create, update, and manage project alerts programmatically.
* Configure alert conditions and notification channels (email, Slack, webhook).
## Response shape
Successful responses return the **resource directly** - there is no envelope, no `isSuccess` discriminator. HTTP status alone (`200/201/204` vs `4xx/5xx`) carries success.
```json theme={null}
{
"id": "alrt_…",
"name": "Daily revenue drop",
"trigger_type": "event",
"status": "active",
"created_at": "2026-04-12T09:32:18.000Z",
"updated_at": "2026-04-25T14:01:55.000Z"
}
```
`DELETE` returns `204 No Content` with an empty body - don't try to parse JSON on those.
### Pagination
List endpoints use a Stripe-style envelope only because they need pagination metadata:
```json theme={null}
{
"data": [
{ "id": "a" },
{ "id": "b" }
],
"page": 1,
"size": 50,
"total": 173,
"has_more": true
}
```
| Field | Meaning |
| ---------- | ----------------------------------------------- |
| `data` | The page of rows |
| `total` | Total count across all pages |
| `page` | 1-indexed page number echoed from the request |
| `size` | Page size echoed from the request |
| `has_more` | `true` if there are pages after the current one |
## Idempotency
Pass an `Idempotency-Key` header on POST/PUT/PATCH/DELETE so retries can't double-create or double-charge. The first response is cached for 24 hours and replayed byte-for-byte on retry.
```http theme={null}
POST /v0/alerts HTTP/1.1
Authorization: Bearer formo_…
Idempotency-Key: 8a3a2b1e-7c4d-4a5e-9c2f-1f8a3a2b1e9f
```
The header is opt-in. See [Idempotency](/api/idempotency) for the full contract, failure modes, and client patterns.
## Errors
Every non-2xx response uses the same envelope:
```json theme={null}
{
"error": {
"code": "BAD_REQUEST",
"message": "Trigger filters must contain at least one entry",
"doc_url": "https://docs.formo.so/api/errors#bad_request",
"param": "body.trigger_filters"
}
}
```
Branch on `error.code` (a stable enum), not `message` or HTTP status alone. The `doc_url` field anchors to the matching section of the [Errors reference](/api/errors), so AI agents can fetch remediation context without escalating to a human.
See [Errors](/api/errors) for the full list of codes.
## Versioning
The public API is mounted under `/v0/`. We treat the path version as a major version; we will add `/v1/` (rather than break `/v0/`) for incompatible changes. While under `/v0/` the contract is settling - breaking changes can land before `/v1/` ships, and we will announce them in the changelog.
Within a version we may add new endpoints, new optional request fields, new response fields (clients should ignore unknown fields), and new error codes within an existing HTTP status family. We will not remove or rename existing endpoints/fields, change the HTTP status of an existing error condition, or repurpose an existing `code` value.
## FAQ
| Layer | Limit | Window |
| --------------------- | --------------- | ---------- |
| API (except Profiles) | 1,000 requests | 15 minutes |
| Profiles API | 10,000 requests | 15 minutes |
| Workspace | 100 requests | 1 second |
Yes. The [Profiles API](/api/profiles/get) returns wallet profile data including holdings, net worth, lifecycle stage, and labels. It also returns your first-party data (if the user has visited your app) such as country, device, browser, OS, and more. You can use this to personalize your app experience based on a user's onchain activity.
Yes. Formo provides [BI tool integration](/data/bi) via BI Read tokens that connect to the Formo data warehouse. You can connect Metabase, Grafana, and other SQL-based tools to query your analytics data.
## Support
Chat with our support team
Email our founder at [yos@formo.so](mailto:yos@formo.so)