Skip to main content

​
Concepts

​
Particles

A particle is a single, focused prompt component:
CategoryPurposeExample
roleWho the AI is”You are a customer support agent”
toneCommunication style”Be friendly and concise”
guardrailsRestrictions”Never share PII”
constraintsOperational limits”Keep responses under 500 words”
formatOutput structure”Respond in markdown”

​
System Prompts

A system prompt combines particles into complete behavior. Each system prompt can include multiple particles, ordered by category (role → tone → guardrails → constraints → format).

​
Create Particle

curl -X POST https://api.cuadra.ai/v1/particles \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Friendly Tone",
    "category": "tone",
    "content": "Respond warmly and conversationally. Use simple language."
  }'

​
Create System Prompt

Compose particles into a complete prompt: 
curl -X POST https://api.cuadra.ai/v1/system-prompts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "particles": [
      {"particleId": "particle_role", "order": 1},
      {"particleId": "particle_tone", "order": 2},
      {"particleId": "particle_guard", "order": 3}
    ]
  }'
Response includes composed content: 
{
  "id": "sysprompt_xyz",
  "name": "Support Bot",
  "composedContent": "You are a support agent. Respond warmly..."
}

​
Attach to Model

curl -X PATCH https://api.cuadra.ai/v1/models/model_abc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"systemPromptId": "sysprompt_xyz"}'

​
Versioning

Particles are automatically versioned. Updates create new versions: 
curl -X PATCH https://api.cuadra.ai/v1/particles/particle_abc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated: Be concise and helpful."}'

​
Pin Versions

Lock a system prompt to specific particle versions for stability: 
{
  "particles": [
    {"particleId": "particle_abc", "particleVersionId": "pv_v2"}
  ]
}

​
Composition Order

Particles are ordered by:
  1. Category priority (fixed): role → tone → guardrails → constraints → format
  2. Order within category (customizable via order field)

​
Best Practices

DoAvoid
Keep particles focused (one purpose)Mixing concerns in one particle
Use consistent namingVague names like “Prompt 1”
Pin versions in productionUnpinned particles in live models
Test changes with new versionsEditing production particles directly

​
FAQ

​
When should I use particles vs. a single prompt?

Use particles when you have multiple models sharing common behavior (same tone, same guardrails). For simple, one-off assistants, a single prompt via the systemPrompt parameter in the Chat API is fine.

​
How do I roll back a particle change?

Pin the system prompt to the previous particle version. Particle versions are immutable—nothing is deleted.

​
Can I override the system prompt at runtime?

Yes. Pass systemPrompt in the Chat API request to override the model’s attached prompt for that specific request.

​
What’s the max prompt length?

No hard limit, but keep total prompt + context under the model’s context window. Aim for under 2,000 tokens for system prompts.

Models API

Attach prompts to models

Chat API

Override prompts at runtime