For developers
A REST API over every Favist resource, personal access tokens that inherit exactly your own permissions, a resolver that turns any link into a structured item, and a tool catalog an AI assistant can call directly.
Create a token in your settings, then ask for your collections. Base URL is https://favist.ai/v1.
curl https://favist.ai/v1/collections \
-H "Authorization: Bearer $FAVIST_TOKEN"The one endpoint worth building against first is the resolver. Give it a URL or a plain phrase and it hands back a structured item with artwork, creator and platform links, across music, film, books, articles, places and products.
curl -X POST https://favist.ai/v1/resolve \
-H "Authorization: Bearer $FAVIST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"input": "https://open.spotify.com/track/..."}'A token never grants access on its own. It resolves to the member who created it, and everything after that runs under row-level security in the database. A token cannot reach anything you could not reach yourself by logging in.
Resources, fields, scopes and verbs live in a single registry. The REST routes, the assistant tool catalog and this page are all generated from it, so a capability arrives on all three surfaces together or on none.
A refused write and a successful one are told apart. When the database refuses something, you get its reason rather than a cheerful empty response.
Fields get added. Fields do not change meaning. Anything that would break a working integration waits for the next version.
10 resources, each with the verbs listed. Omitted verbs are omitted on purpose rather than missing.
| Path | What it is | Verbs |
|---|---|---|
| /v1/collections | A named group of favorites, public, unlisted or private. | list, get, create, update, delete |
| /v1/items | One favorite inside a collection. The join carries per-owner overrides. | list, get, create, update, delete |
| /v1/todos | A task, one-off or recurring, with optional reminders. | list, get, create, update, delete |
| /v1/goals | Something being worked toward, with progress. | list, get, create, update, delete |
| /v1/streaks | A habit, with its check-in history. | list, get, create, update, delete |
| /v1/messages | A direct message. Blocks and attachment consent apply. | list, get, create |
| /v1/follows | Who you follow. Blocked pairs are refused by policy. | list, create, delete |
| /v1/channels | A public destination of its own, separate from the member's profile. | list, get, create, update |
| /v1/collection-types | Which of the collection types this member has switched on. | list, update |
| /v1/profile | The authenticated member's own profile. | get, update |
Turn a URL or a search phrase into a structured catalog item.
Returns a song_id usable directly when creating an item. Rate limited harder than the rest, since each call may reach an upstream provider.
Search the catalog by name across every collection type.
Record today's check-in for a streak.
A verb, not a row: check-ins are append-only and the streak's own state is derived, so exposing the table would invite writes that corrupt the count.
Mint a short-lived presigned URL to upload media directly.
Bytes never pass through this API. Pro only, and the plan is checked against the token's own member.
Uniform across every endpoint, because integration platforms depend on that far more than on any single endpoint being clever.
The resources that will fire triggers are already declared, signed with HMAC-SHA256 on X-Favist-Signature, with at-least-once delivery. Delivery itself is not shipped yet, and neither are the connectors that would sit on top of it, so this is written here as a plan rather than as something you can build against today.
Favist publishes its capabilities as a tool catalog, so an AI assistant can add a favorite, search a collection or build a list on someone's behalf. It is the same set of tools Fave uses inside Favist, which means nothing is quietly available in here and missing out there.
# The catalog: every capability as a callable tool definition
curl https://favist.ai/api/agent/tools \
-H "Authorization: Bearer $FAVIST_TOKEN"
# Run one
curl -X POST https://favist.ai/api/agent/invoke \
-H "Authorization: Bearer $FAVIST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"tool": "search", "input": {"query": "radiohead"}}'A handful of tools return a directive for the browser to carry out rather than running on the server, because playing a song or listening on the microphone has to happen where the person is.
It is the endpoint that is genuinely hard to replicate, and it takes one request to see why.