Getting started
This guide walks through making your first authenticated request.
1. Get an API key
API keys are minted from the Feathr app. Each key is opaque — Feathr stores only a hash of it, so the secret is shown once at creation and cannot be recovered afterward. Copy it somewhere safe.
A key looks like:
fthr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
When you create a key you also choose its scopes — the set of operations it
may perform (for example persons:read or tags:write). Grant only the scopes
the integration needs.
2. Make a request
Send the key as a bearer token in the Authorization header:
curl https://api.feathr.co/me \
-H "Authorization: Bearer $FEATHR_API_KEY"
GET /me returns the identity and scopes behind the key — a quick way to
confirm your credentials work:
{
"account_id": "5f8e...c21a",
"scopes": ["persons:read", "tags:write"],
"key_id": "6a1b...9f30"
}
3. Call an endpoint
List the persons in your account. GET /persons requires at least one of
updated_since, email, or external_id. Passing updated_since returns
everyone last seen at or after that timestamp (no more than 30 days ago):
curl "https://api.feathr.co/persons?updated_since=2024-01-01T00:00:00Z&page=1&size=50" \
-H "Authorization: Bearer $FEATHR_API_KEY"
The response is an offset-paginated Page envelope:
{
"items": [{ "id": "...", "email": "..." }],
"page": 1,
"size": 50,
"total": 327
}
Fetch the next page by incrementing page; you've read everything once
page * size >= total.
Next steps
- Authentication — scopes and error handling in depth.
- API Reference — the complete endpoint catalog.