# Presets

Content generation presets

## List all presets

> Returns a list of AI instruction presets that can be used when creating content.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/presets":{"get":{"summary":"List all presets","description":"Returns a list of AI instruction presets that can be used when creating content.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"},"description":"Page number for pagination"}],"responses":{"200":{"description":"A list of presets","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}}}}}},"tags":["Presets"]}}}}
```

## POST /v1/presets

> Create a new preset

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"CreatePreset":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":500},"presets":{"type":"object","description":"Preset settings. All fields are optional.","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings.","properties":{"image_model":{"type":"string"},"image_style":{"type":"string"},"image_count_body":{"type":"integer","minimum":0,"maximum":20},"use_brand_colors":{"type":"boolean"},"image_extra_prompt":{"type":"string"}}},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"extra_prompt":{"type":"string","maxLength":50000},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}},"PresetDetail":{"allOf":[{"$ref":"#/components/schemas/Preset"},{"type":"object","properties":{"presets":{"type":"object","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"enable_pplx_fetch":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_featured_image":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"include_youtube_videos":{"type":"boolean"},"position_key_takeaways":{"type":"string","enum":["none","top","bottom"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings stored in the preset.","properties":{"image_model":{"type":"string","description":"Image model (e.g. gpt-image-1, flux-schnell, flux-dev, flux-pro)"},"image_style":{"type":"string","description":"Image style (professional, photorealistic, cinematic, auto, etc.)"},"image_count_body":{"type":"integer","minimum":0,"maximum":20,"description":"Max number of images in the article body"},"use_brand_colors":{"type":"boolean","description":"Apply brand kit colors to generated images"},"image_extra_prompt":{"type":"string","description":"Custom instructions for image generation"}}},"extra_prompt":{"type":"string"},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}}]},"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/presets":{"post":{"summary":"Create a new preset","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePreset"}}}},"responses":{"201":{"description":"Preset created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresetDetail"}}}}},"tags":["Presets"]}}}}
```

## GET /v1/presets/{id}

> Get a preset by ID

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PresetDetail":{"allOf":[{"$ref":"#/components/schemas/Preset"},{"type":"object","properties":{"presets":{"type":"object","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"enable_pplx_fetch":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_featured_image":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"include_youtube_videos":{"type":"boolean"},"position_key_takeaways":{"type":"string","enum":["none","top","bottom"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings stored in the preset.","properties":{"image_model":{"type":"string","description":"Image model (e.g. gpt-image-1, flux-schnell, flux-dev, flux-pro)"},"image_style":{"type":"string","description":"Image style (professional, photorealistic, cinematic, auto, etc.)"},"image_count_body":{"type":"integer","minimum":0,"maximum":20,"description":"Max number of images in the article body"},"use_brand_colors":{"type":"boolean","description":"Apply brand kit colors to generated images"},"image_extra_prompt":{"type":"string","description":"Custom instructions for image generation"}}},"extra_prompt":{"type":"string"},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}}]},"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/presets/{id}":{"get":{"summary":"Get a preset by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"},"description":"The preset ID"}],"responses":{"200":{"description":"The preset with full settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresetDetail"}}}}},"tags":["Presets"]}}}}
```

## PUT /v1/presets/{id}

> Update a preset

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"CreatePreset":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":500},"presets":{"type":"object","description":"Preset settings. All fields are optional.","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings.","properties":{"image_model":{"type":"string"},"image_style":{"type":"string"},"image_count_body":{"type":"integer","minimum":0,"maximum":20},"use_brand_colors":{"type":"boolean"},"image_extra_prompt":{"type":"string"}}},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"extra_prompt":{"type":"string","maxLength":50000},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}},"PresetDetail":{"allOf":[{"$ref":"#/components/schemas/Preset"},{"type":"object","properties":{"presets":{"type":"object","properties":{"language":{"type":"string"},"location":{"type":"string"},"tone":{"type":"string","enum":["seo_optimized","casual","excited","formal","friendly","humorous","professional"]},"pov":{"type":"string","enum":["first_person_singular","first_person_plural","second_person","third_person"]},"article_type":{"type":"string","enum":["general","listicle","review","howto"]},"target_length":{"type":"string","enum":["short","medium","long"]},"enable_pplx_fetch":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"include_faq":{"type":"boolean"},"include_featured_image":{"type":"boolean"},"include_meta_description":{"type":"boolean"},"include_youtube_videos":{"type":"boolean"},"position_key_takeaways":{"type":"string","enum":["none","top","bottom"]},"include_ai_images":{"type":"boolean"},"ai_image_meta":{"type":"object","description":"Image generation settings stored in the preset.","properties":{"image_model":{"type":"string","description":"Image model (e.g. gpt-image-1, flux-schnell, flux-dev, flux-pro)"},"image_style":{"type":"string","description":"Image style (professional, photorealistic, cinematic, auto, etc.)"},"image_count_body":{"type":"integer","minimum":0,"maximum":20,"description":"Max number of images in the article body"},"use_brand_colors":{"type":"boolean","description":"Apply brand kit colors to generated images"},"image_extra_prompt":{"type":"string","description":"Custom instructions for image generation"}}},"extra_prompt":{"type":"string"},"knowledge_sources":{"type":"array","items":{"type":"integer"}}}}}}]},"Preset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target_content_type":{"type":"string","enum":["general","location_page"],"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/presets/{id}":{"put":{"summary":"Update a preset","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"},"description":"The preset ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePreset"}}}},"responses":{"200":{"description":"Preset updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresetDetail"}}}}},"tags":["Presets"]}}}}
```

## DELETE /v1/presets/{id}

> Delete a preset

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Presets","description":"Content generation presets"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/presets/{id}":{"delete":{"summary":"Delete a preset","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"},"description":"The preset ID"}],"responses":{"204":{"description":"Preset deleted"}},"tags":["Presets"]}}}}
```


---

# 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/presets.md?ask=<question>
```

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.