Projects

Bulk content generation projects

Fetch list of projects

get

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Responses

200

A list of projects

application/json

get

/v1/projects

HTTPcURLJavaScriptPython

GET /v1/projects HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of projects

[
  {
    "id": "text",
    "name": "text",
    "created_at": "2026-02-04T17:21:04.177Z",
    "updated_at": "2026-02-04T17:21:04.177Z"
  }
]

Create a new project

post

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

project_namestring · max: 100Required

Name of the project

site_idstring · uuid · nullableOptional

Optional site/brand ID. When provided, enables Brand Voice, site context, target audience, and Link Engine for all articles in the project. Use GET /v1/sites to list available sites.

modelstringOptional

The model to use for the article. Use the /v1/meta/models endpoint to get available models.

Default: gpt-4o-mini

common_settings_presetnumber · nullableOptional

The settings preset to use for the project. Use the common_settings object to override specific settings. Go to your presets to create a preset.

target_keywordsstring[] · min: 1 · max: 600Required

The target keywords to generate content for.

Responses

200

Project created successfully

application/json

post

/v1/projects

HTTPcURLJavaScriptPython

POST /v1/projects HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 807

{
  "project_name": "text",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "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"
  ]
}

200

Project created successfully

{
  "id": "text",
  "name": "text",
  "articles": {
    "ANY_ADDITIONAL_PROPERTY": "initializing"
  },
  "created_at": "2026-02-04T17:21:04.177Z",
  "updated_at": "2026-02-04T17:21:04.177Z"
}

Get a project by ID

get

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The ID of the project

Responses

200

The project object

application/json

get

/v1/projects/{id}

HTTPcURLJavaScriptPython

GET /v1/projects/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

The project object

{
  "id": "text",
  "name": "text",
  "articles": {
    "ANY_ADDITIONAL_PROPERTY": "initializing"
  },
  "created_at": "2026-02-04T17:21:04.177Z",
  "updated_at": "2026-02-04T17:21:04.177Z"
}

Export project articles

get

Export all completed articles from a project in JSON or CSV format. This endpoint is useful for bulk exporting content to external systems like Airtable, spreadsheets, or custom CMS integrations.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstringRequired

The ID of the project to export

Query parameters

formatstring · enumOptional

The export format. Use csv for spreadsheet-compatible output.

Default: jsonPossible values:

fieldsstringOptional

Comma-separated list of fields to include in the export. Available fields: title, slug, content, excerpt, date, image, target_keyword, keywords, language, model, pov, tone. Default: title,slug,content,excerpt,image,target_keyword,language,model

session_idstring · nullableOptional

Filter articles by bulk session ID (optional)

statusstring · enumOptional

Filter by article status. Use complete to only export finished articles, or all to include in-progress articles.

Default: completePossible values:

Responses

200

Exported articles

application/jsontext/csv

404

No articles found for this project

application/json

get

/v1/projects/{id}/export

HTTPcURLJavaScriptPython

GET /v1/projects/{id}/export HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "articles": [
    {
      "title": "text",
      "slug": "text",
      "content": "text",
      "excerpt": "text",
      "date": "2026-02-04T17:21:04.177Z",
      "image": "text",
      "target_keyword": "text",
      "keywords": "text",
      "language": "text",
      "model": "text",
      "pov": "text",
      "tone": "text"
    }
  ]
}