Council API

Open Access with BYOK: The Council API is now open to everyone using Bring Your Own Key (BYOK). Just provide your own Groq API key using the dual-key format. Managed keys (where we provide the Groq key) are still in beta — contact us to request access.

The Demeterics Council API provides a multi-persona evaluation system for any type of written content. Get diverse perspectives by querying a council of AI personas representing different segments of the US population.

Overview

Base URL: https://api.demeterics.com/council/v1

Features:

• Diverse Perspectives: 18 M.E.C.E. personas spanning demographics, professions, and communication styles
• Flexible Evaluation: Works for any content type - emails, marketing copy, creative writing, documentation
• Parallel Execution: All persona evaluations run concurrently for fast response times
• Smart Aggregation: Final synthesis call combines insights into actionable feedback
• Overall Score: Returns a 0-100 score for easy content comparison
• Auto-tracking: Every request logged to BigQuery with full observability
• BYOK Support: Use your own Groq API keys with dual-key authentication

Authentication

Bring Your Own Key (BYOK) — Recommended

Use the dual-key format to provide your own Groq API key. This is open to everyone — no approval required.

curl -X POST https://api.demeterics.com/council/v1/evaluate \
  -H "Authorization: Bearer dmt_your_api_key;gsk_your_groq_key" \
  -H "Content-Type: application/json" \
  -d '{...}'

The format is: [demeterics_api_key];[groq_api_key]

BYOK Benefits:

• Open access — start using immediately after signup
• 10% service fee instead of 15%
• Use your own rate limits and quotas
• Provider costs billed directly to your Groq account

Managed Keys (Beta)

Beta Access Required: Managed keys are currently in beta. Contact us to request access.

Use only your Demeterics API key (we provide the Groq key):

curl -X POST https://api.demeterics.com/council/v1/evaluate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{...}'

Endpoints

Evaluate Content

POST /council/v1/evaluate

Submit content for multi-persona evaluation.

Request Body:

*At least one of question or content must be provided. The question field is key for providing context about how you want the content evaluated.

Example Request:

curl -X POST https://api.demeterics.com/council/v1/evaluate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How would you rate this customer apology email?",
    "content": "Dear valued customer, We sincerely apologize for the delay in your order. We understand how frustrating this must be and are working to resolve the issue...",
    "num_personas": 8
  }'

Response:

{
  "id": "council_01JARV4HZ6XPQMWVCS9N1GKEFD",
  "score": 72,
  "summary": "The apology email strikes a professional tone but feels somewhat generic. Younger audiences and busy professionals want more specifics - what caused the delay and when will it be resolved? The phrase 'valued customer' reads as corporate template language. Consider adding a concrete timeline, specific compensation offer, and a more personal touch. Older audiences and those valuing professionalism found it acceptable but not memorable.",
  "persona_responses": [
    {
      "name": "Zoe",
      "description": "16-year-old high schooler who values brevity and clarity",
      "interested_level": 58,
      "clarity_flags": ["valued customer", "working to resolve"],
      "guidance": "Too formal and vague. Just tell me when my stuff arrives. 'Valued customer' is so corporate.",
      "duration_ms": 823
    },
    {
      "name": "Kevin",
      "description": "27-year-old Asian-American AI engineer, analytical thinker",
      "interested_level": 75,
      "clarity_flags": ["no timeline"],
      "guidance": "Missing key information: root cause and expected resolution date. The apology is sincere but actionable details would make it more useful.",
      "duration_ms": 756
    }
  ],
  "stats": {
    "total_personas": 8,
    "successful_responses": 8,
    "failed_responses": 0,
    "average_interested_level": 72.5,
    "promoters": 2,
    "passives": 5,
    "detractors": 1,
    "consensus": "moderate",
    "total_duration_ms": 2450,
    "parallel_duration_ms": 1230
  },
  "usage": {
    "persona_call_count": 8,
    "aggregation_call_count": 1,
    "total_call_count": 9,
    "total_prompt_tokens": 4520,
    "total_completion_tokens": 2180,
    "total_tokens": 6700,
    "model": "openai/gpt-oss-20b",
    "aggregation_model": "openai/gpt-oss-120b",
    "provider_cost_usd": 0.00245,
    "service_cost_usd": 0.00037,
    "total_cost_usd": 0.00282,
    "billing_mode": "managed"
  }
}

List Personas

GET /council/v1/personas

List all available personas for council evaluation.

Example Request:

curl -X GET "https://api.demeterics.com/council/v1/personas" \
  -H "Authorization: Bearer dmt_your_api_key"

Response:

{
  "personas": [
    {
      "name": "Maya",
      "description": "19-year-old Gen Z college student from NYC, values authenticity and bold expression",
      "story_vibe_lens": "Appreciates confident, direct communication. Dislikes anything that feels fake or corporate.",
      "category": "gen_z"
    },
    {
      "name": "Kevin",
      "description": "27-year-old Asian-American AI engineer, analytical thinker who values precision",
      "story_vibe_lens": "Appreciates well-structured arguments and clear reasoning. Notices logical inconsistencies.",
      "category": "young_adult_tech"
    }
  ],
  "total_count": 18,
  "categories": ["gen_z", "young_adult_tech", "young_adult_diy", "young_adult_creative", "young_adult_professional", "young_adult_lifestyle", "accessibility", "millennial_culture", "millennial_urban", "millennial_family", "millennial_history", "genx_working_class", "genx_sports", "genx_business", "boomer_educated", "technical"]
}

Personas

The council includes 18 diverse personas representing a M.E.C.E. (Mutually Exclusive, Collectively Exhaustive) cross-section of the US population:

Gen Z (16-19)

Young Adults (20-29)

Millennials/Gen X (30-44)

Gen X / Boomers (45+)

Technical

Scoring System

Each persona rates content on a 0-100 scale based on:

1. Effectiveness: Does the content achieve its purpose?
2. Tone & Voice: Is the tone appropriate for the context?
3. Quality: Is it well-written and engaging?

Score Ranges:

• 0-20: Poor - significant issues
• 21-40: Below average - notable problems
• 41-60: Average - acceptable but improvable
• 61-80: Good - effective with minor suggestions
• 81-100: Excellent - highly effective

Response Categories

Voting Feature

When you provide a question asking personas to choose, pick, or compare options, each persona will cast a vote for their preferred option along with a brief reason based on their unique perspective.

How It Works

1. Include multiple options in your content (labeled A, B, C or 1, 2, 3, etc.)
2. Ask a question that requires choosing (e.g., "Which story would you most want to watch?")
3. Each persona votes based on their emotions, experience, and worldview
4. The API tallies votes and determines a winner (random tie-breaking if needed)

Voting Response Fields

When voting is enabled, each persona_response includes:

The stats object includes:

Voting Example Request

curl -X POST https://api.demeterics.com/council/v1/evaluate \
  -H "Authorization: Bearer dmt_your_api_key;gsk_your_groq_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which story would you most want to watch as a short video?",
    "content": "A) John Paul Jones raises the first American flag on a warship in 1775, cannons firing, sailors cheering.\n\nB) Dr. Christiaan Barnard performs the first human heart transplant in 1967, a tense operating room, the heart begins to beat.\n\nC) Astronomer discovers a new moon of Jupiter in 1904, peering through a telescope, expanding humanitys map of the solar system.\n\nD) Edith Sampson becomes the first African-American female judge in 1962, gavel in hand, courtroom applause.",
    "num_personas": 12
  }'

Voting Example Response

{
  "id": "council_01JARV4HZ6XPQMWVCS9N1GKEFD",
  "score": 78,
  "summary": "The council strongly favored Story A (John Paul Jones) for its visual drama, patriotic appeal, and broad accessibility...",
  "persona_responses": [
    {
      "name": "Maya",
      "description": "19-year-old Gen Z college student from NYC",
      "interested_level": 82,
      "vote": "A",
      "vote_reason": "The flag moment is super visual and iconic for a short video.",
      "guidance": "Lead with the cannon fire and cheering for maximum impact."
    },
    {
      "name": "Carlos",
      "description": "23-year-old Latino mechanic near the Texas border",
      "interested_level": 75,
      "vote": "B",
      "vote_reason": "Heart transplant is real heroic work, saving someone's life matters.",
      "guidance": "Show the surgeons' hands, the tension, the moment of success."
    },
    {
      "name": "Susan",
      "description": "60-year-old retired teacher and history lover",
      "interested_level": 85,
      "vote": "A",
      "vote_reason": "The birth of American naval power is historically significant and visually compelling.",
      "guidance": "Include context about the Revolutionary War for educational value."
    }
  ],
  "stats": {
    "total_personas": 12,
    "successful_responses": 12,
    "average_interested_level": 78.3,
    "vote_breakdown": {
      "A": 7,
      "B": 3,
      "C": 1,
      "D": 1
    },
    "majority_vote": "A",
    "vote_consensus": "58%",
    "consensus": "moderate"
  }
}

Use Cases

Customer Email Review

{
  "question": "How effective is this customer apology email?",
  "content": "Dear valued customer, We sincerely apologize for the inconvenience...",
  "num_personas": 8
}

Marketing Copy Testing

{
  "question": "Would this email subject line make you want to open the email?",
  "content": "Your exclusive offer expires tonight",
  "num_personas": 8
}

Creative Writing Feedback

{
  "question": "How would you rate this opening paragraph for a novel?",
  "content": "The rain fell like needles on the cobblestones as Sarah stepped out of the cab...",
  "num_personas": 12
}

Documentation Review

{
  "question": "Is this API documentation clear and helpful?",
  "content": "To authenticate, include your API key in the Authorization header...",
  "num_personas": 6
}

Social Media Post

{
  "question": "Would this LinkedIn post engage professionals?",
  "content": "3 lessons I learned from failing my first startup...",
  "num_personas": 8
}

Poetry/Creative Content

{
  "question": "How would you rate the following poem?",
  "content": "The roses are red,\nThe sky is blue,\nThe blushes are green,\nAnd the sun like you",
  "num_personas": 8
}

Content Selection (Voting)

{
  "question": "Which headline would make you click to read more?",
  "content": "A) Scientists Discover New Planet in Habitable Zone\nB) Local Dog Saves Family from House Fire\nC) Tech Giant Announces Revolutionary AI Breakthrough\nD) Ancient Treasure Found in Backyard",
  "num_personas": 12
}

Pricing

Billing Model

Council evaluations are billed as N+1 LLM calls:

• N persona evaluation calls (using model)
• 1 aggregation/synthesis call (using aggregation_model)

Managed Keys (15% service fee)

Example cost for 9 personas (based on real usage):

• 9 persona calls @ ~1.5K tokens each = ~$0.002
• 1 aggregation call @ ~2K tokens = ~$0.0005
• Total: $0.0025 + 15% fee = **$0.003 per evaluation**
• Typical: ~16K tokens per council evaluation

BYOK (10% service fee)

Use your own Groq API key. 10% service fee on top of provider costs.

Error Handling

Error Response Format:

{
  "error": {
    "type": "validation_error",
    "message": "num_personas must be between 2 and 18",
    "code": "validation_error"
  }
}

Common Error Codes:

SDK Support

Python

import requests

response = requests.post(
    "https://api.demeterics.com/council/v1/evaluate",
    headers={"Authorization": "Bearer dmt_your_api_key"},
    json={
        "question": "How effective is this customer email?",
        "content": "Your email content here...",
        "num_personas": 8
    }
)

result = response.json()
print(f"Overall Score: {result['score']}/100")
print(f"Summary: {result['summary']}")

Node.js

const response = await fetch("https://api.demeterics.com/council/v1/evaluate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer dmt_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    question: "How effective is this customer email?",
    content: "Your email content here...",
    num_personas: 8
  })
});

const result = await response.json();
console.log(`Score: ${result.score}/100`);

n8n Integration

Use the Demeterics Council node in n8n to integrate multi-persona evaluation into your workflows. Perfect for:

• Customer communication review
• Marketing copy testing
• Content quality assessment
• A/B testing different versions

Best Practices

1. Provide clear context in your question: The question field sets the evaluation criteria. "How effective is this apology email?" gives better results than "Is this good?"

2. Match persona count to use case:

   • Quick feedback: 4-6 personas
   • Standard evaluation: 8 personas
   • Comprehensive analysis: 12-18 personas

3. Use the score for comparison: The 0-100 score lets you easily compare different versions of content

4. Read individual responses: The aggregated summary is useful, but individual persona feedback often contains specific actionable insights

5. Consider your audience: If your content targets a specific demographic, pay extra attention to feedback from matching personas