---
title: "Save to a collection (free)"
method: POST
path: "/api/v1/collections"
---

# Save to a collection (free)

`POST /api/v1/collections`

## Request

- Base URL: `https://invokely.ai`
- URL: `https://invokely.ai/api/v1/collections`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
  - none

Save a statistic page to one of the user's collections when they ask to keep, bookmark or save it. Without collection it goes to the default collection, "Saved". Saving the same page again keeps one item and updates its note.
What to save: an indicator and a place (a value), an indicator and a ranking scope (a ranking, scope as in the ranking URL: "us-states", "eu-countries", "countries", "texas-counties"), an indicator alone, a place alone, a topic or a publisher. kind is inferred when left out.
Examples: {"indicator": "unemployment_rate", "place": "Texas"}. {"indicator": "gdp_per_capita_usd", "scope": "countries", "note": "For the board deck"}. {"kind": "topic", "topic": "labour", "collection": "col_3f9a..."}.
Returns {collection: {id, name, visibility}, item: {id, kind, note?}, created, dashboard_url}. A collection holds up to 100 items. Free on every plan.

## Request body

- object
  - `kind` 'value' | 'ranking' | 'indicator' | 'place' | 'topic' | 'publisher': Optional. value, ranking, indicator, place, topic or publisher.
  - `indicator` string: Indicator id, for example "unemployment_rate".
  - `place` string: Place name or id, for example "Texas" or "es-mun-08121".
  - `scope` string: Ranking scope, for example "us-states".
  - `topic` string: Topic id or slug, for example "labour" or "labor-market".
  - `publisher` string: Publisher id or slug, for example "bls" or "ine".
  - `collection` string: Optional collection id from list_collections. Default: the user's "Saved" collection.
  - `note` string: Optional note shown with the item.

## Response `200`

The item was already saved: {collection, item, created: false, dashboard_url}.

- Data
  - `data` unknown, required

## Other responses

- `201`: A new item: {collection, item, created: true, dashboard_url}.
- `400`: Invalid argument (INVALID_ARGUMENT).
- `401`: API key required (UNAUTHORIZED).
- `404`: Unknown indicator or place, or no data (INDICATOR_NOT_FOUND, PLACE_NOT_FOUND, AMBIGUOUS_PLACE, NO_DATA). hint and suggestions say what to try next.
- `409`: Collection full (LIMIT_REACHED).
- `429`: More than 60 collection calls a minute (RATE_LIMITED).

---

[API](https://skmtc.dev/invokely/apis/invokely-statistics-api.md) · [All operations](https://skmtc.dev/invokely/apis/invokely-statistics-api/llms.txt) · [OpenAPI document](https://skmtc.dev/invokely/apis/invokely-statistics-api/revisions/3b0f775bccb6?raw)