API reference
A small, predictable REST API. Base URL https://api.recommend.co.
Authentication
Authenticate every request with a Bearer API key from your dashboard. Keep keys server-side.
Authorization: Bearer rcmd_...
Objects
List the objects you follow and read any object’s live state.
/v1/objectsList objects
List the objects your workspace follows — the watchlist.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Max items to return. Default 50. |
| cursor | string | Pagination cursor from a previous response. |
curl https://api.recommend.co/v1/objects \ -H "Authorization: Bearer $RECOMMEND_API_KEY"
{
"data": [
{ "object": "demand:facial-spf", "state": 73, "verdict": "watch" },
{ "object": "demand:protein-coffee", "state": 81, "verdict": "healthy" }
],
"next": null
}/v1/objects/{id}/stateGet object state
The live state of a followed object — score, verdict, trajectory, driver, and move.
| Parameter | Type | Description |
|---|---|---|
| id | string | The object id, e.g. demand:facial-spf. |
curl https://api.recommend.co/v1/objects/demand:facial-spf/state \ -H "Authorization: Bearer $RECOMMEND_API_KEY"
{
"object": "demand:facial-spf",
"state": 73,
"verdict": "watch",
"trajectory": [58, 63, 69, 73],
"driver": "rising search volume + repeat-purchase intent",
"move": "Brief 2 creators before the UV peak",
"settles_on": "purchase window + 14 days",
"calibration": "held 7 of last 10"
}Search
Resolve a free-text query to an object.
/v1/searchSearch objects
Resolve or find an object — an entity, a category, or a theme.
| Parameter | Type | Description |
|---|---|---|
| q | string | Free-text query, e.g. "facial spf". |
curl "https://api.recommend.co/v1/search?q=facial+spf" \ -H "Authorization: Bearer $RECOMMEND_API_KEY"
{
"results": [
{ "object": "demand:facial-spf", "name": "Facial SPF", "type": "category" }
]
}Trajectory
Read an object’s state history over time.
/v1/objects/{id}/trajectoryGet trajectory
State history for an object over a time window.
| Parameter | Type | Description |
|---|---|---|
| id | string | The object id. |
| window | string | Time window, e.g. 30d. Default 30d. |
curl "https://api.recommend.co/v1/objects/demand:facial-spf/trajectory?window=30d" \ -H "Authorization: Bearer $RECOMMEND_API_KEY"
{
"object": "demand:facial-spf",
"points": [
{ "t": "2026-05-22", "state": 58 },
{ "t": "2026-05-29", "state": 63 },
{ "t": "2026-06-05", "state": 69 },
{ "t": "2026-06-12", "state": 73 }
]
}Errors
Standard HTTP status codes. Error bodies include a message.
| Status | Meaning | When |
|---|---|---|
| 401 | Unauthorized | Missing or invalid API key. |
| 404 | Not found | No object matches that id. |
| 429 | Rate limited | Too many requests — back off and retry. |
| 5xx | Server error | Something went wrong on our side; retry with backoff. |
Rate limits
Limits scale with your plan. See pricing for query volumes.
| Plan | Rate | Included volume |
|---|---|---|
| Free | 60 req / min | 10,000 queries / month |
| Pay-as-you-go | 600 req / min | Metered, volume discounts |
| Team | 1,200 req / min | 50,000 queries / month + overage |
| Enterprise | Custom | Committed volume |
We're putting the finishing touches on this section. Try the live playground in the meantime.
Try the playground