Overview
Particles are modular prompt components that can be combined into system prompts. Each particle has a specific purpose (role, tone, guardrails) and is automatically versioned.
Create Particle
curl -X POST https://api.cuadra.ai/v1/particles \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Professional Tone",
"category": "tone",
"content": "Communicate professionally. Use clear, concise language."
}'
Response
{
"id": "particle_abc123",
"name": "Professional Tone",
"category": "tone",
"content": "Communicate professionally...",
"currentVersion": 1,
"tokenCount": 12,
"createdAt": "2025-01-19T12:00:00Z"
}
Categories
| Category | Order | Purpose |
|---|
role | 1 | Define the AI persona |
tone | 2 | Set communication style |
guardrails | 3 | Restrict behavior |
context | 4 | Provide background info |
format | 5 | Control output structure |
order field.
List Particles
curl https://api.cuadra.ai/v1/particles \
-H "Authorization: Bearer YOUR_TOKEN"
Filter by Category
curl "https://api.cuadra.ai/v1/particles?category=guardrails" \
-H "Authorization: Bearer YOUR_TOKEN"
Get Particle
curl https://api.cuadra.ai/v1/particles/particle_abc123 \
-H "Authorization: Bearer YOUR_TOKEN"
Get Specific Version
curl "https://api.cuadra.ai/v1/particles/particle_abc123?version=2" \
-H "Authorization: Bearer YOUR_TOKEN"
Update Particle
Updates create a new version automatically:
curl -X PATCH https://api.cuadra.ai/v1/particles/particle_abc123 \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "Updated: Be professional and empathetic."}'
Response
{
"id": "particle_abc123",
"name": "Professional Tone",
"content": "Updated: Be professional and empathetic.",
"currentVersion": 2,
"tokenCount": 10
}
Delete Particle
curl -X DELETE https://api.cuadra.ai/v1/particles/particle_abc123 \
-H "Authorization: Bearer YOUR_TOKEN"
Deleting a particle affects all system prompts using it. Unlink from system prompts first.
Version History
List all versions of a particle:
curl https://api.cuadra.ai/v1/particles/particle_abc123/versions \
-H "Authorization: Bearer YOUR_TOKEN"
Response
{
"data": [
{"version": 2, "content": "Updated...", "createdAt": "2025-01-19T14:00:00Z"},
{"version": 1, "content": "Original...", "createdAt": "2025-01-19T12:00:00Z"}
]
}
Example Particles
Role: Customer Support
{
"name": "Support Agent",
"category": "role",
"content": "You are a helpful customer support agent for Acme Corp. Your goal is to resolve issues efficiently while maintaining a positive experience."
}
Guardrails: No PII
{
"name": "No PII Disclosure",
"category": "guardrails",
"content": "Never reveal personal information including email addresses, phone numbers, addresses, or payment details. If asked, direct users to contact support directly."
}
{
"name": "Markdown Output",
"category": "format",
"content": "Format responses using Markdown. Use headers for sections, bullet points for lists, and code blocks for technical content."
}
Errors
| Status | Error | Description |
|---|
| 400 | Invalid category | Category not recognized |
| 404 | Particle not found | ID does not exist |
| 409 | Name conflict | Particle name already exists |
