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 role1 Define the AI persona tone2 Set communication style guardrails3 Restrict behavior constraints4 Operational limits format5 Control output structure
Categories are composed in fixed order. Within each category, you control ordering via the 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
System Prompts Compose particles into prompts
Models API Attach prompts to models
