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
POST /v1/particles
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."
}'
import httpx
response = httpx.post(
"https://api.cuadra.ai/v1/particles",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={
"name": "Professional Tone",
"category": "tone",
"content": "Communicate professionally. Use clear, concise language."
}
)
particle = response.json()
const response = await fetch('https://api.cuadra.ai/v1/particles', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Professional Tone',
category: 'tone',
content: 'Communicate professionally. Use clear, concise language.'
})
});
const particle = await response.json();
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 |
constraints | 4 | Operational limits |
format | 5 | Control output structure |
order field.
List Particles
curl https://api.cuadra.ai/v1/particles \
-H "Authorization: Bearer YOUR_TOKEN"
import httpx
response = httpx.get(
"https://api.cuadra.ai/v1/particles",
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
particles = response.json()["data"]
const response = await fetch('https://api.cuadra.ai/v1/particles', {
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const { data: particles } = await response.json();
Filter by Category
curl "https://api.cuadra.ai/v1/particles?category=guardrails" \
-H "Authorization: Bearer YOUR_TOKEN"
response = httpx.get(
"https://api.cuadra.ai/v1/particles",
params={"category": "guardrails"},
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
const response = await fetch('https://api.cuadra.ai/v1/particles?category=guardrails', {
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
Get Particle
curl https://api.cuadra.ai/v1/particles/particle_abc123 \
-H "Authorization: Bearer YOUR_TOKEN"
import httpx
response = httpx.get(
"https://api.cuadra.ai/v1/particles/particle_abc123",
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
particle = response.json()
const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc123', {
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const particle = await response.json();
Get Specific Version
curl "https://api.cuadra.ai/v1/particles/particle_abc123?version=2" \
-H "Authorization: Bearer YOUR_TOKEN"
response = httpx.get(
"https://api.cuadra.ai/v1/particles/particle_abc123",
params={"version": 2},
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc123?version=2', {
headers: { '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."}'
import httpx
response = httpx.patch(
"https://api.cuadra.ai/v1/particles/particle_abc123",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={"content": "Updated: Be professional and empathetic."}
)
particle = response.json()
print(f"New version: {particle['currentVersion']}")
const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc123', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({ content: 'Updated: Be professional and empathetic.' })
});
const particle = await response.json();
console.log(`New version: ${particle.currentVersion}`);
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"
import httpx
response = httpx.delete(
"https://api.cuadra.ai/v1/particles/particle_abc123",
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
# Returns 204 No Content on success
const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc123', {
method: 'DELETE',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
// Returns 204 No Content on success
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"
import httpx
response = httpx.get(
"https://api.cuadra.ai/v1/particles/particle_abc123/versions",
headers={"Authorization": "Bearer YOUR_TOKEN"}
)
versions = response.json()["data"]
const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc123/versions', {
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const { data: versions } = await response.json();
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."
}
Format: Markdown
{
"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 |
Related
System Prompts
Compose particles into prompts
Models API
Attach prompts to models