Categories
Particles are organized into five categories, composed in this order:
| Priority | Category | Purpose | Example |
|---|
| 1 | role | Identity | ”You are a customer support agent” |
| 2 | tone | Communication style | ”Be professional and empathetic” |
| 3 | guardrails | Safety constraints | ”Never share internal docs” |
| 4 | constraints | Operational limits | ”Keep responses under 500 words” |
| 5 | format | Output 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."}'
Token Budget Guidelines
Keep particles concise for cost efficiency:
| Category | Recommended | Why |
|---|
| Role | 50-100 tokens | Core identity only |
| Tone | 25-50 tokens | Style, not examples |
| Guardrails | 50-150 tokens | Critical safety rules |
| Constraints | 25-75 tokens | Specific limits |
| Format | 25-50 tokens | Structure only |
| Total | 175-425 tokens | Leaves room for context |
Use GET /v1/particles/{id} to see tokenCount for each particle. The compose endpoint shows total token usage.
