API reference
Use the Cuppa API to generate content and images using AI. The capabilities of the API are defined in the next sections.
Authentication
To use the API, you need to authenticate using an API key. Go to your Cuppa settings to obtain an API key. Include the API key in the X-API-KEY header of your requests as follows:
curl -X GET "https://api.cuppa.ai/v1/meta" \
-H "accept: application/json" \
-H "X-API-KEY: YOUR_API_KEY"Rate Limiting
The API has rate limits in place to ensure fair usage.
Error Handling
The API returns standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response will contain an error object with details about the error.
GET /v1/meta HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*
Metadata object
{
"languages": [
{
"name": "text",
"code": "text"
}
],
"regions": [
{
"name": "text",
"code": "text"
}
],
"models": [
"text"
],
"image_models": [
"text"
]
}Maximum number of images to return (max 50, default 20)
GET /v1/images HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*
A list of generated images
[
{
"id": "text",
"url": "text"
}
]The model to use for image generation. Use the /v1/meta/image_models endpoint to get available image models.
The prompt to use for image generation
POST /v1/images HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 86
{
"model": "text",
"prompt": "text",
"settings": {
"size": "1792x1024",
"aspect_ratio": "16:9"
}
}Successfully generated image
{
"id": "text",
"url": "text"
}Page number for pagination
Filter by language code
Filter by project ID. If not provided, it will return the articles not part of any project. Use all to get all articles.
GET /v1/contents HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*
A list of articles
[
{
"id": "text",
"is_draft": true,
"status": "initializing",
"title": "text",
"content": "text",
"snippet": "text",
"project_id": "text",
"meta_description": "text",
"featured_images": [
{
"url": "text",
"alt": "text"
}
],
"content_type": "article",
"settings": {
"model": "text",
"target_keyword": "text",
"language": "text",
"region": "text"
},
"created_at": "2025-06-26T12:26:50.826Z",
"updated_at": "2025-06-26T12:26:50.826Z"
}
]The target_keyword for the article.
The model to use for the article.
gpt-4o-miniThe settings preset to use for the article. Use the settings object to override specific settings. Go to your presets to create a preset.
Whether the article is a draft
falsePOST /v1/contents HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 792
{
"target_keyword": "text",
"model": "gpt-4o-mini",
"outline": [
{
"type": "heading",
"level": 2,
"title": "text"
}
],
"settings_preset": 1,
"settings": {
"language": "text",
"region": "text",
"tone": "seo_optimized",
"pov": "first_person_plural",
"article_type": "general",
"fetch_perplexity": false,
"include_introduction": true,
"include_conclusion": true,
"include_yt_suggestions": false,
"generate_faqs": false,
"generate_meta_description": false,
"key_takeaways_position": "none",
"include_stock_images": false,
"generate_images": false,
"image_settings": {
"model": "dall-e-3",
"max_body_images_count": 1,
"style_preset": "photorealistic",
"custom_style": {
"name": "text",
"description": "text"
}
},
"advanced_settings": {
"title_prompt": "text",
"introduction_prompt": "text",
"section_prompt": "text",
"meta_description_prompt": "text"
}
},
"is_draft": false
}Article created successfully
{
"id": "text",
"is_draft": true,
"status": "initializing",
"status_extra": {
"error": "text"
}
}The ID of the article
GET /v1/contents/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*
The article object
{
"id": "text",
"is_draft": true,
"status": "initializing",
"title": "text",
"content": "text",
"snippet": "text",
"project_id": "text",
"meta_description": "text",
"featured_images": [
{
"url": "text",
"alt": "text"
}
],
"content_type": "article",
"settings": {
"model": "text",
"target_keyword": "text",
"language": "text",
"region": "text"
},
"created_at": "2025-06-26T12:26:50.826Z",
"updated_at": "2025-06-26T12:26:50.826Z"
}The ID of the article
GET /v1/contents/{id}/status HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*
The status of the article
{
"id": "text",
"is_draft": true,
"status": "initializing",
"status_extra": {
"error": "text"
}
}GET /v1/projects HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*
A list of projects
[
{
"id": "text",
"name": "text",
"created_at": "2025-06-26T12:26:50.826Z",
"updated_at": "2025-06-26T12:26:50.826Z"
}
]Name of the project
The model to use for the article. Use the /v1/meta/models endpoint to get available models.
gpt-4o-miniThe settings preset to use for the project. Use the common_settings object to override specific settings. Go to your presets to create a preset.
The target keywords to generate content for.
POST /v1/projects HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 758
{
"project_name": "text",
"model": "gpt-4o-mini",
"common_settings_preset": 1,
"common_settings": {
"language": "text",
"region": "text",
"tone": "seo_optimized",
"pov": "first_person_plural",
"article_type": "general",
"fetch_perplexity": false,
"include_introduction": true,
"include_conclusion": true,
"include_yt_suggestions": false,
"generate_faqs": false,
"generate_meta_description": false,
"key_takeaways_position": "none",
"include_stock_images": false,
"generate_images": false,
"image_settings": {
"model": "dall-e-3",
"max_body_images_count": 1,
"style_preset": "photorealistic",
"custom_style": {
"name": "text",
"description": "text"
}
},
"advanced_settings": {
"title_prompt": "text",
"introduction_prompt": "text",
"section_prompt": "text",
"meta_description_prompt": "text"
}
},
"target_keywords": [
"text"
]
}Project created successfully
{
"id": "text",
"name": "text",
"articles": {
"ANY_ADDITIONAL_PROPERTY": "initializing"
},
"created_at": "2025-06-26T12:26:50.826Z",
"updated_at": "2025-06-26T12:26:50.826Z"
}The ID of the project
GET /v1/projects/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*
The project object
{
"id": "text",
"name": "text",
"articles": {
"ANY_ADDITIONAL_PROPERTY": "initializing"
},
"created_at": "2025-06-26T12:26:50.826Z",
"updated_at": "2025-06-26T12:26:50.826Z"
}Last updated