Skip to main content

​
Overview

The Generations API creates AI-powered content using pre-built templates with optional brand voice styling. Generate blog posts, social media content, email campaigns, product descriptions, and more. Each template has specific input_data fields—list generation apps to discover available templates and their parameters.

​
Typical Flow

1

List generation apps

Call GET /generation-apps to see available templates, their app_id, descriptions, and required input_data fields.
2

Create a generation

Call POST /generations with app_id, input_data (template-specific), optional brand_voice_id, and workspace_id. Some apps return immediately; others may run asynchronously (poll or use webhook if supported).
3

Read the output

Response includes output (text) and often markdown. Check usage.credits_used for cost.

​
Available Templates

Browse generation apps to find templates and their input structure: 
import requests

response = requests.get(
    "https://app.mavera.io/api/v1/generation-apps",
    headers={"Authorization": "Bearer mvra_live_your_key_here"}
)

data = response.json()
if "error" in data:
    raise Exception(data["error"]["message"])

apps = data["data"]
for app in apps:
    print(f"{app['id']}: {app.get('name', app['id'])}")
    print(f"  Description: {app.get('description', '')[:80]}...")
    print(f"  Input schema: {app.get('input_schema', app.get('input_data', {}))}")

​
Creating Content

Pass app_id (from generation apps), input_data (fields required by that template), optional brand_voice_id, and workspace_id. 
response = requests.post(
    "https://app.mavera.io/api/v1/generations",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "app_id": "blog_post_generator",
        "title": "Q1 Product Launch Blog",
        "brand_voice_id": "bv_abc123",  # Optional — apply brand voice
        "input_data": {
            "topic": "New Product Features",
            "target_audience": "Small business owners",
            "tone": "professional yet approachable",
            "length": "1000 words"
        },
        "workspace_id": "your_workspace_id"
    }
)

generation = response.json()
if "error" in generation:
    raise Exception(generation["error"]["message"])

print(f"Content:\n{generation['output']}")
print(f"Credits used: {generation.get('usage', {}).get('credits_used')}")

​
Common input_data Fields

Different templates expect different fields. Typical examples:
FieldExampleDescription
topic”Product launch”Main subject
target_audience”SMB owners”Who it’s for
tone”professional, friendly”Writing tone
length”500 words”Desired length
key_points[“Feature A”, “Pricing”]Bullet points to include
platform”LinkedIn”For social templates
Check GET /generation-apps for the exact schema per template.

​
Response Format

{
  "id": "gen_abc123",
  "title": "Q1 Product Launch Blog",
  "app": "blog_post_generator",
  "output": "# Introducing Our Latest Features\n\nWe're excited to announce...",
  "markdown": "# Introducing Our Latest Features...",
  "content_type": "MARKDOWN",
  "status": "COMPLETED",
  "usage": {
    "credits_used": 15
  }
}
If the generation runs asynchronously, status may be PENDING or RUNNING. Poll GET /generations/{id} until status is COMPLETED.

​
Polling for Completion (Async Generations)

Some templates process asynchronously. Poll until status is COMPLETED: 
import time

def wait_for_generation(gen_id, max_wait_minutes=5):
    for _ in range(max_wait_minutes * 6):
        resp = requests.get(
            f"https://app.mavera.io/api/v1/generations/{gen_id}",
            headers={"Authorization": "Bearer mvra_live_your_key_here"}
        )
        data = resp.json()
        if data.get("status") == "COMPLETED":
            return data
        time.sleep(10)
    raise TimeoutError("Generation did not complete")

​
List Generations

curl https://app.mavera.io/api/v1/generations \
  -H "Authorization: Bearer mvra_live_your_key_here"
Optionally filter by workspace_id, app_id, or paginate with cursor and limit.

​
Delete a Generation

curl -X DELETE https://app.mavera.io/api/v1/generations/gen_abc123 \
  -H "Authorization: Bearer mvra_live_your_key_here"

​
Credit Costs

OperationTypical Cost
Create generation10–30 credits
Depends on template, output lengthLonger content = more credits
Check usage.credits_used in each response. See Credits for your plan.

​
Best Practices

Pass brand_voice_id from a Brand Voice profile so output matches your tone and vocabulary.
Clear topic, target_audience, and key_points produce better output than vague prompts.
Call GET /generation-apps to discover templates and required fields before building your integration.

Brand Voice

Create and use brand voice profiles

Credits

Credit allocation and tracking

API Reference

Full API specification