Skip to main content

​
Categories

Particles are organized into five categories, composed in this order:
PriorityCategoryPurposeExample
1roleIdentity”You are a customer support agent”
2toneCommunication style”Be professional and empathetic”
3guardrailsSafety constraints”Never share internal docs”
4constraintsOperational limits”Keep responses under 500 words”
5formatOutput formatting”Use markdown with headers”

​
Quick Start

curl -X POST https://api.cuadra.ai/v1/particles \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Professional Support Agent",
    "category": "role",
    "content": "You are a professional customer support agent. Always be helpful, empathetic, and solution-oriented.",
    "description": "Primary support persona"
  }'

​
Automatic Versioning

Content changes create a new version automatically: 
# Version 1
curl -X POST /v1/particles -d '{"content": "You are a support agent."}'

# Update → Version 2
curl -X PUT /v1/particles/part_abc -d '{"content": "You are a professional support agent."}'
System prompts using unpinned particles automatically get the latest version.

​
Token Budget Guidelines

Keep particles concise for cost efficiency:
CategoryRecommendedWhy
Role50-100 tokensCore identity only
Tone25-50 tokensStyle, not examples
Guardrails50-150 tokensCritical safety rules
Constraints25-75 tokensSpecific limits
Format25-50 tokensStructure only
Total175-425 tokensLeaves room for context
Use GET /v1/particles/{id} to see tokenCount for each particle. The compose endpoint shows total token usage.

System Prompts API

Compose particles into prompts

Particles Guide

Best practices