Roundups API

Base URL: https://roundups.ai/api/v1

Generation is async (typically 1–5 minutes). The create endpoint returns immediately with a roundup id; poll the fetch endpoint to check status and retrieve the article.

Auth header (required for all requests):

Authorization: Bearer <api_key>

Endpoints:

POST /api/v1/roundups — create a roundup (returns immediately, generation runs in background).
GET /api/v1/roundups/:id — fetch a roundup status and article.

Quick links:

Create Roundup
Fetch Roundup
Required Parameters
High-Level Parameters
Content Settings
Fetching Status / Result
Error Handling

Create Roundup

POST /api/v1/roundups

Creates a roundup and starts generation in the background. Returns a response with the roundup id and state.

Responses:

202 Accepted — request accepted, generation started (JSON body).
4xx — validation/authorization errors (JSON body with errors).

1) Required Parameters (one of these is required)

You must provide at least one of the following fields:

headline (string)
target_audience (string)
keywords (string)

Example curl (minimal):

curl -X POST "https://roundups.ai/api/v1/roundups" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": "Best office chairs for long workdays"
  }'

2) High-Level Parameters (product/source selection)

Optional fields that control product sourcing and selection:

product_type (string, default: amazon)
- allowed: amazon, appsumo, envato, unified
- rewardful is not supported
- if product_urls is present:
  - Amazon URL → product_type becomes amazon
  - non-Amazon URL → product_type becomes unified
products_count (integer)
- number of products to select for Amazon/Appsumo/Envato
- if not provided, we infer from the headline or pick 3/5/10
products_search_queries (array[string], max 10)
- search queries for Amazon/Appsumo/Envato
amazon_product_asins (array[string], max 50)
- explicit ASINs for Amazon selection (overrides search queries)
product_urls (array[string], max 50)
- required when product_type is unified

Limits:

products_count max: 50
amazon_product_asins max: 50
product_urls max: 50

Examples:

Amazon from headline only (auto picks categories + product count):

curl -X POST "https://roundups.ai/api/v1/roundups" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": "Top 10 ergonomic office chairs for long workdays"
  }'

Amazon with explicit products_count:

curl -X POST "https://roundups.ai/api/v1/roundups" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": "Best office chairs for long workdays",
    "product_type": "amazon",
    "products_count": 5
  }'

Amazon with ASINs:

curl -X POST "https://roundups.ai/api/v1/roundups" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": "standing desk setup",
    "product_type": "amazon",
    "amazon_product_asins": ["B08X2JQ7SC", "B07Z2RBPV5", "B09QG1Y1KB"]
  }'

Amazon with search queries:

curl -X POST "https://roundups.ai/api/v1/roundups" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "target_audience": "remote workers who want ergonomic setups",
    "product_type": "amazon",
    "products_count": 6,
    "products_search_queries": ["ergonomic chair", "standing desk", "desk lamp"]
  }'

Unified (URLs are required, product_type auto-detected):

curl -X POST "https://roundups.ai/api/v1/roundups" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": "Top website builders for small businesses",
    "product_urls": [
      "https://example.com/product-one",
      "https://example.com/product-two"
    ]
  }'

3) Content Settings (styles, tone, output, etc.)

All content settings are optional. Provide them under the styles object.

Allowed keys:

tone_of_voice
language
comparison_table_enabled
point_of_view
custom_cta
include_pricing
include_rating
optimize_output_for
llm_model
cover_image_style
visual_style
layout_style
template_type

Allowed values:

tone_of_voice:
- Conversational, Informative, Persuasive, Humorous, Inspirational, Reflective, Authoritative, Critical, Formal, Cautionary, Sarcastic
point_of_view:
- Second Person (You), First Person (I, We), Third Person (He, She, They, It)
language:
- English, English (UK), German, Japanese, French, Italian, Spanish, Hindi, Dutch, Chinese, Polish, Swedish, Arabic, Turkish, Portuguese (Brazil), English (Australia), English (Canada), Spanish (Mexico), Arabic (Saudi Arabia), Arabic (UAE), Arabic (Egypt), Dutch (Belgium), Korean, Russian, Hebrew, Greek, Romanian, Czech, Hungarian, Danish, Finnish, Norwegian, Slovak, Ukrainian, Croatian, Bulgarian, Portuguese, Vietnamese, Thai, Indonesian, Malay, Bengali, Urdu, Persian, Tagalog, Tamil, Telugu, Marathi, Gujarati, Kannada, Chinese (Simplified), Chinese (Traditional), Albanian, Georgian, Moldovan, Mongolian, Armenian, Montenegrin, Awadhi, Nepali, Azerbaijani, Haryanvi, Bashkir, Oriya, Basque, Pashto, Belarusian, Irish, Bhojpuri, Bosnian, Punjabi, Javanese, Rajasthani, Cantonese (Yue), Kashmiri, Catalan, Kazakh, Sanskrit, Chhattisgarhi, Konkani, Santali, Serbian, Kyrgyz, Sindhi, Latvian, Sinhala, Lithuanian, Dogri, Macedonian, Slovenian, Maithili, Estonian, Maltese, Faroese, Mandarin Chinese, Uzbek, Marwari, Welsh, Galician, Min Nan, Wu
optimize_output_for:
- roundups_ai, wordpress, ghost_cms, email_distribution, medium
llm_model:
- basic, enhanced
cover_image_style:
- generative, product
visual_style:
- basic, charts
layout_style:
- product_box, showcase, youtube
template_type:
- default, awards

Example:

curl -X POST "https://roundups.ai/api/v1/roundups" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": "best budgeting apps",
    "product_type": "appsumo",
    "styles": {
      "tone_of_voice": "Informative",
      "language": "English",
      "point_of_view": "Second Person (You)",
      "comparison_table_enabled": true,
      "include_pricing": true,
      "include_rating": true,
      "llm_model": "basic",
      "visual_style": "basic",
      "layout_style": "product_box",
      "template_type": "default"
    }
  }'

Fetch Roundup

GET https://roundups.ai/api/v1/roundups/:id

Fetches the current state of a roundup and returns the article when it’s ready.

Responses:

200 OK — roundup found (JSON body).
404 Not Found — invalid id.

Fetching Status / Result

Poll the roundup:

curl -X GET "https://roundups.ai/api/v1/roundups/<id>" \
  -H "Authorization: Bearer <api_key>"

Response shape:

{
  "id": 123,
  "headline": "Top 10 ergonomic office chairs for long workdays",
  "state": "generating",
  "created_at": "2026-01-19T13:13:39Z",
  "updated_at": "2026-01-19T13:13:39Z",
  "article": null,
  "errors": null
}

Example response with article:

{
  "id": 123,
  "headline": "Top 10 ergonomic office chairs for long workdays",
  "state": "draft",
  "created_at": "2026-01-19T13:13:39Z",
  "updated_at": "2026-01-19T13:18:12Z",
  "article": {
    "id": 987,
    "title": "Top 10 ergonomic office chairs for long workdays",
    "content": "<div>...html...</div>",
    "featured_image": "https://roundups-public.s3.eu-central-1.amazonaws.com/uploads/article/8128cd43d8571b045242f/7664a0986c1cbb561574a.webp",
    "meta_description": "Short SEO description here.",
    "created_at": "2026-01-19T13:18:12Z"
  },
  "errors": null
}

When state is generating, article is null. Once finished, article contains the generated content. If processing fails, errors will contain the failure message.

Error Handling

Validation and generation failures are and returned in errors field as a string.
If background processing fails, the Roundup moves to state: timeout and errors is populated.

kirillshevch/roundups_api.md

Select an option

No results found