# Projects
Bulk content generation projects
## GET /v1/projects
> Fetch list of projects
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/projects":{"get":{"summary":"Fetch list of projects","responses":{"200":{"description":"A list of projects","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"tags":["Projects"]}}}}
```
## POST /v1/projects
> Create a new project
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentSettings":{"type":"object","required":["language","region"],"properties":{"language":{"type":"string","description":"The language of the article."},"region":{"type":"string","description":"The region of the article."},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"],"default":"seo_optimized","description":"The tone of the article."},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"],"default":"first_person_plural","description":"The point of view of the article."},"article_type":{"type":"string","enum":["general","listicle","review","howto","recipe"],"default":"general","description":"The type of the article."},"fetch_perplexity":{"type":"boolean","default":false,"description":"Whether to use Perplexity for fetching real-time research data. It requires a Perplexity API key."},"include_introduction":{"type":"boolean","default":true,"description":"Whether to include an introduction section in the article."},"include_conclusion":{"type":"boolean","default":true,"description":"Whether to include a conclusion section in the article."},"include_yt_suggestions":{"type":"boolean","default":false,"description":"Whether to include YouTube suggestions in the article."},"generate_faqs":{"type":"boolean","default":false,"description":"Whether to generate a FAQ section in the article."},"generate_meta_description":{"type":"boolean","default":false,"description":"Whether to generate a meta description for the article."},"key_takeaways_position":{"type":"string","default":"none","enum":["top","bottom","none"],"description":"The position of the key takeaways section in the article. Use `none` to disable it."},"include_stock_images":{"type":"boolean","default":false,"description":"Whether to include stock featured images in the article."},"generate_images":{"type":"boolean","default":false,"description":"Whether to generate AI images for the article. Use the `image_settings` object to configure image generation."},"image_settings":{"type":"object","properties":{"model":{"type":"string","default":"gpt-image-1","description":"The image model to use for generation. Use the `/v1/meta/image_models` endpoint to get available image models."},"max_body_images_count":{"type":"integer","minimum":0,"maximum":7,"description":"The maximum number of images to generate in the body. Use `0` to disable body images."},"style_preset":{"type":"string","enum":["vintage","professional","photorealistic","infographic","minimalist_art","comic","watercolor_painting","abstract_art","pop_art","model_3d","line_art"],"nullable":true,"default":"photorealistic","description":"The style preset for the images. Use `custom_style` if you prefer a custom style instead."},"custom_style":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"The name of the custom style."},"description":{"type":"string","description":"The description of the custom style. This should be a short but detailed description of the style you want to apply to the images."}},"description":"The custom style for the images."}}},"advanced_settings":{"type":"object","properties":{"title_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the title."},"introduction_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the introduction."},"section_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the sections."},"meta_description_prompt":{"type":"string","maxLength":20000,"nullable":true,"description":"The prompt to use for generating the meta description."}}}}},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"articles":{"type":"object","description":"A record of article IDs and their corresponding task status","additionalProperties":{"$ref":"#/components/schemas/TaskStatus"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/projects":{"post":{"summary":"Create a new project","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_name":{"type":"string","description":"Name of the project","maxLength":100},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"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."},"model":{"type":"string","description":"The model to use for the article. Use the `/v1/meta/models` endpoint to get available models.","default":"gpt-4o-mini"},"common_settings_preset":{"type":"number","description":"The settings preset to use for the project. Use the `common_settings` object to override specific settings. Go to your [presets](https://app.cuppa.ai/presets/my) to create a preset.","nullable":true},"common_settings":{"$ref":"#/components/schemas/ContentSettings","description":"The common settings to use for the project. Use the `common_settings_preset` property to specify a preset."},"target_keywords":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":600,"description":"The target keywords to generate content for."}},"required":["project_name","target_keywords"]}}}},"responses":{"200":{"description":"Project created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}}},"tags":["Projects"]}}}}
```
## GET /v1/projects/{id}
> Get a project by ID
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"articles":{"type":"object","description":"A record of article IDs and their corresponding task status","additionalProperties":{"$ref":"#/components/schemas/TaskStatus"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"TaskStatus":{"type":"string","enum":["initializing","waiting","progress","canceled","complete","failed"]}}},"paths":{"/v1/projects/{id}":{"get":{"summary":"Get a project by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the project"}],"responses":{"200":{"description":"The project object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}}},"tags":["Projects"]}}}}
```
## Export project articles
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Bulk content generation projects"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ExportedArticle":{"type":"object","description":"An exported article with the requested fields","properties":{"title":{"type":"string","description":"The article title"},"slug":{"type":"string","description":"URL-friendly slug derived from the target keyword"},"content":{"type":"string","description":"The full HTML content of the article"},"excerpt":{"type":"string","nullable":true,"description":"The meta description or excerpt"},"date":{"type":"string","format":"date-time","description":"The article creation date"},"image":{"type":"string","nullable":true,"description":"URL of the featured image"},"target_keyword":{"type":"string","description":"The target keyword for the article"},"keywords":{"type":"string","nullable":true,"description":"Additional keywords"},"language":{"type":"string","description":"The language of the article (e.g., \"English\")"},"model":{"type":"string","description":"The AI model used for generation"},"pov":{"type":"string","description":"The point of view (e.g., \"First Person Plural\")"},"tone":{"type":"string","description":"The tone of voice (e.g., \"Professional\")"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/projects/{id}/export":{"get":{"summary":"Export project articles","description":"Export all completed articles from a project in JSON or CSV format. \nThis endpoint is useful for bulk exporting content to external systems like Airtable, spreadsheets, or custom CMS integrations.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The ID of the project to export"},{"in":"query","name":"format","schema":{"type":"string","enum":["json","csv"],"default":"json"},"description":"The export format. Use `csv` for spreadsheet-compatible output."},{"in":"query","name":"fields","schema":{"type":"string"},"description":"Comma-separated list of fields to include in the export. \nAvailable fields: `title`, `slug`, `content`, `excerpt`, `date`, `image`, `target_keyword`, `keywords`, `language`, `model`, `pov`, `tone`.\nDefault: `title,slug,content,excerpt,image,target_keyword,language,model`\n"},{"in":"query","name":"session_id","schema":{"type":"string","nullable":true},"description":"Filter articles by bulk session ID (optional)"},{"in":"query","name":"status","schema":{"type":"string","enum":["complete","all"],"default":"complete"},"description":"Filter by article status. Use `complete` to only export finished articles, or `all` to include in-progress articles."}],"responses":{"200":{"description":"Exported articles","content":{"application/json":{"schema":{"type":"object","properties":{"articles":{"type":"array","items":{"$ref":"#/components/schemas/ExportedArticle"}}}}},"text/csv":{"schema":{"type":"string","description":"CSV formatted article data"}}}},"404":{"description":"No articles found for this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Projects"]}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://learn.cuppa.ai/rest-api/projects.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.