Cuadra AI - Connect, Train, and Deploy Your Custom AI Assistant

Concepts

Particles

A particle is a single, focused prompt component:

Category	Purpose	Example
`role`	Who the AI is	”You are a customer support agent”
`tone`	Communication style	”Be friendly and concise”
`guardrails`	Restrictions	”Never share PII”
`constraints`	Operational limits	”Keep responses under 500 words”
`format`	Output 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."
  }'

import httpx

response = httpx.post(
    "https://api.cuadra.ai/v1/particles",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "name": "Friendly Tone",
        "category": "tone",
        "content": "Respond warmly and conversationally. Use simple 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: 'Friendly Tone',
    category: 'tone',
    content: 'Respond warmly and conversationally. Use simple language.'
  })
});
const particle = await response.json();

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 = httpx.post(
    "https://api.cuadra.ai/v1/system-prompts",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "name": "Support Bot",
        "particles": [
            {"particleId": "particle_role", "order": 1},
            {"particleId": "particle_tone", "order": 2}
        ]
    }
)
system_prompt = response.json()

const response = await fetch('https://api.cuadra.ai/v1/system-prompts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Support Bot',
    particles: [
      { particleId: 'particle_role', order: 1 },
      { particleId: 'particle_tone', order: 2 }
    ]
  })
});
const systemPrompt = await response.json();

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"}'

import httpx

response = httpx.patch(
    "https://api.cuadra.ai/v1/models/model_abc",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"systemPromptId": "sysprompt_xyz"}
)
print("System prompt attached to model")

const response = await fetch('https://api.cuadra.ai/v1/models/model_abc', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ systemPromptId: 'sysprompt_xyz' })
});
console.log('System prompt attached to model');

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."}'

import httpx

response = httpx.patch(
    "https://api.cuadra.ai/v1/particles/particle_abc",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"content": "Updated: Be concise and helpful."}
)
particle = response.json()
print(f"New version: {particle['currentVersion']}")

const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ content: 'Updated: Be concise and helpful.' })
});
const particle = await response.json();
console.log(`New version: ${particle.currentVersion}`);

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:

Category priority (fixed): role → tone → guardrails → constraints → format
Order within category (customizable via order field)

Best Practices

Do	Avoid
Keep particles focused (one purpose)	Mixing concerns in one particle
Use consistent naming	Vague names like “Prompt 1”
Pin versions in production	Unpinned particles in live models
Test changes with new versions	Editing 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

Getting Started

API Reference

Guides

Billing

System Prompts

Concepts

Particles

System Prompts

Create Particle

Create System Prompt

Attach to Model

Versioning

Pin Versions

Composition Order

Best Practices

FAQ

When should I use particles vs. a single prompt?

How do I roll back a particle change?

Can I override the system prompt at runtime?

What’s the max prompt length?

Models API

Chat API

​Concepts

​Particles

​System Prompts

​Create Particle

​Create System Prompt

​Attach to Model

​Versioning

​Pin Versions

​Composition Order

​Best Practices

​FAQ

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

​How do I roll back a particle change?

​Can I override the system prompt at runtime?

​What’s the max prompt length?

​Related

Models API

Chat API

Concepts

Particles

System Prompts

Create Particle

Create System Prompt

Attach to Model

Versioning

Pin Versions

Composition Order

Best Practices

FAQ

When should I use particles vs. a single prompt?

How do I roll back a particle change?

Can I override the system prompt at runtime?

What’s the max prompt length?

Related