Curated for You Curations API
The Curations API from Curated for You — 1 operation(s) for curations.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/curated-for-you:curated-for-you-curations-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Curated for You Curations API
description: '# API Usage Guide
## Overview
The Curated for You API provides endpoints to manage and retrieve
information authentication, curations, companies, and attributes. This
guide will help you understand how to authenticate and interact with
the API effectively. Your permissions are setup beforehand when you
join the organization, for additional permissions please contact your
customer care representative.
## Authentication
The Curated for You API uses OAuth 2.0 Bearer token
authentication. Follow these steps to authenticate your requests:
```bash
curl -X POST ''https://api.curatedforyou.io/api/v1/user/login'' \
-H ''Content-Type: application/x-www-form-urlencoded'' \
--data-urlencode ''username=your_email@example.com'' \
--data-urlencode ''password=your_password''
```
### Use the Token
After a successful login, you will receive a token. This token lasts
for 30 minutes(?). Include the received token in the Authorization header
for all subsequent requests
```bash
curl -G ''https://api.curatedforyou.io/api/v2/endpoint'' \
-H ''Authorization: Bearer ENTER_AUTH_TOKEN_HERE'' \
-H ''accept: application/json''
```
## Get Curation Products Guide
### 1. Get Company Information
Retrieve the companies you have access to:
```bash
curl -G ''https://api.curatedforyou.io/api/v2/companies'' \
-H ''Authorization: Bearer ENTER_AUTH_TOKEN_HERE'' \
-H ''accept: application/json'' \
-d ''projection=code_name'' \
-d ''projection=display_name''
```
In this example, we use projection limit our response to only
`display_name` and the `code_name`.
### 2. Get Curations
Use the found `company_id` to get the curations within that company:
```bash
curl -G ''https://api.curatedforyou.io/api/v2/curations'' \
-H ''Authorization: Bearer ENTER_AUTH_TOKEN_HERE'' \
-H ''accept: application/json'' \
-d ''company_id=ENTER_COMPANY_ID_HERE'' \
-d ''sort_by=created_at:desc'' \
-d ''limit=50'' \
-d ''offset=0'' \
-d ''projection=curation_display_name'' \
-d ''projection=curation_group_number'' \
-d ''projection=curation_description'' \
-d ''projection=export_page_url_handle'' \
-d ''projection=company_product_ids''
```
This example shows the different ways we can return information by
specifying different projections.
### 3. Get Most Recent Snapshot
After finding your specific curation we can query the snapshot that
was exported to determine what information we should be displaying.
The curation_group_number is the important id to use and the
information on how and what was exported can be found in the
`meta_data` field.
```bash
curl -G ''https://api.curatedforyou.io/api/v2/curation_snapshots'' \
-H ''Authorization: Bearer ENTER_AUTH_TOKEN_HERE'' \
-H ''accept: application/json'' \
-d ''company_id=ENTER_COMPANY_ID_HERE'' \
-d ''curation_group_number=CURATION_GROUP_NUMBER_HERE'' \
-d ''sort_by=created_at:desc'' \
-d ''limit=50'' \
-d ''offset=0'' \
-d ''projection=products'' \
-d ''projection=meta_data'' \ # <<< where the last export time is found
-d ''projection=display_name'' \
-d ''projection=created_at''
```'
version: 2.0.1
x-logo:
url: https://app.curatedforyou.io/cfy_logo.png
tags:
- name: Curations
x-displayName: Curations
paths:
/api/v2/curations/:
get:
tags:
- Curations
summary: Fetch Curations
description: 'This endpoint returns filtered and sorted curations based on specified query parameters. The response includes
pagination information and supports projection to customize the fields returned.
### Terminology
- Curation Group Number: A permanent unique identifier assigned to each curation that remains constant even if the curation is renamed or modified
- Company Product ID: An external product identifier provided by the customer for integration purposes
### Brief fields
- page_type, division, story_duration_type, marketing_strategy and
parent_curation_cgn are returned when requested in projection.
Values are taken from curation_briefs.attributes for this company and CGN with scope "curation".
- Table columns can be filtered with table_filters and sorted with sort_by.'
operationId: fetch_curations_api_v2_curations__get
parameters:
- name: company_id
in: query
required: true
schema:
type: integer
description: 'Company ID that owns the curations.
Required for filtering curations and permission checks.'
title: Company Id
description: 'Company ID that owns the curations.
Required for filtering curations and permission checks.'
example: 1
- name: curation_ids
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: Filter by curation IDs (including private pinned curations).
title: Curation Ids
description: Filter by curation IDs (including private pinned curations).
- name: table_filters
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'JSON table filters keyed by column: {"division":{"values":["Womens"]},"workflow_status":{"values":["approved"]},"created_at":{"presets":["last_7_days"]}}. Text columns accept {"search":"text"}; date columns accept presets last_7_days, last_30_days, last_90_days, and never for nullable dates.'
title: Table Filters
description: 'JSON table filters keyed by column: {"division":{"values":["Womens"]},"workflow_status":{"values":["approved"]},"created_at":{"presets":["last_7_days"]}}. Text columns accept {"search":"text"}; date columns accept presets last_7_days, last_30_days, last_90_days, and never for nullable dates.'
- name: curation_group_number
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: 'Filter by Curation Group Numbers (CGNs).
Multiple CGNs can be provided to filter for multiple groups.'
title: Curation Group Number
description: 'Filter by Curation Group Numbers (CGNs).
Multiple CGNs can be provided to filter for multiple groups.'
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'Search keyword to filter curations by display name.
Uses case-insensitive partial matching.'
title: Search
description: 'Search keyword to filter curations by display name.
Uses case-insensitive partial matching.'
- name: sort_by
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'Sort parameter in format ''field:direction:is_nulls_last''.
Defaults to ''curation_display_name:asc:true'' if not specified.
**Available sort fields:**
- curation_display_name: Sort by display name
- product_count: Sort by number of products
- last_export_date: Sort by last export date
- has_brief: Sort by whether curation brief exists
- freeze_body.frozen_at: Sort by when the curation was frozen
**Direction values:**
- asc: Ascending order
- desc: Descending order**is_nulls_last values:**
- true: Null values appear last
- false: Null values appear first
'
title: Sort By
description: 'Sort parameter in format ''field:direction:is_nulls_last''.
Defaults to ''curation_display_name:asc:true'' if not specified.
**Available sort fields:**
- curation_display_name: Sort by display name
- product_count: Sort by number of products
- last_export_date: Sort by last export date
- has_brief: Sort by whether curation brief exists
- freeze_body.frozen_at: Sort by when the curation was frozen
**Direction values:**
- asc: Ascending order
- desc: Descending order**is_nulls_last values:**
- true: Null values appear last
- false: Null values appear first
'
example: created_at:desc
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
description: 'Maximum number of curations to return.
Used for pagination.'
default: 50
title: Limit
description: 'Maximum number of curations to return.
Used for pagination.'
example: 50
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: 'Number of curations to skip.
Used for pagination.'
default: 0
title: Offset
description: 'Number of curations to skip.
Used for pagination.'
example: 0
- name: projection
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: '**Available Fields:**
id, curation_display_name, curation_group_number, curation_description, export_page_url_handle, export_page_header, export_page_description, export_page_meta_title, export_page_meta_description, promoted_to_live_at, last_export_date, created_at, updated_at, geo, settings, product_count, company_product_ids
**Additional optional fields:**
page_type, division, story_duration_type, marketing_strategy, parent_curation_cgn — from the curation brief (scope=curation); null when missing or invalid. workflow_status, workflow_status_label, has_export_page_description.'
title: Projection
description: '**Available Fields:**
id, curation_display_name, curation_group_number, curation_description, export_page_url_handle, export_page_header, export_page_description, export_page_meta_title, export_page_meta_description, promoted_to_live_at, last_export_date, created_at, updated_at, geo, settings, product_count, company_product_ids
**Additional optional fields:**
page_type, division, story_duration_type, marketing_strategy, parent_curation_cgn — from the curation brief (scope=curation); null when missing or invalid. workflow_status, workflow_status_label, has_export_page_description.'
example:
- id
- curation_display_name
- curation_group_number
- curation_description
- export_page_url_handle
- company_product_ids
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
responses:
'200':
description: Successful Response
content:
application/json:
schema:
title: Response Fetch Curations Api V2 Curations Get
examples:
default:
summary: Default Response
value:
data:
- id: 123
curation_display_name: Summer Collection 2024
curation_group_number: 456
curation_group_name: Summer Collections
version_status: live
product_count: 42
first_product:
product_id: 789
image_url: https://example.com/image.jpg
product_name: Summer Dress
total: 100
limit: 50
offset: 0
'400':
description: Bad Request
content:
application/json:
examples:
invalid_status:
summary: Invalid Status
value:
detail: 'Invalid status fields: [invalid_status]'
'403':
description: Forbidden
content:
application/json:
examples:
no_permission:
summary: No Permission
value:
detail: You do not have permission to read curations.
restricted_status:
summary: Restricted Status
value:
detail: You do not have permission to read updating/inactive/archived curations.
'404':
description: Not Found
content:
application/json:
example:
detail: Company not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
x-provenance:
method: harvested
publisher: Curated for You
source: https://api.curatedforyou.io/api/schema.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)