> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cuadra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# System Prompts

> Configure AI behavior with modular, versioned system prompts. Compose reusable particles for role, tone, guardrails, and output formatting.

## 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

<CodeGroup>
  ```bash curl theme={null}
  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."
    }'
  ```

  ```python Python theme={null}
  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()
  ```

  ```typescript Node.js theme={null}
  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();
  ```
</CodeGroup>

***

## Create System Prompt

Compose particles into a complete prompt:

<CodeGroup>
  ```bash curl theme={null}
  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}
      ]
    }'
  ```

  ```python Python theme={null}
  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()
  ```

  ```typescript Node.js theme={null}
  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();
  ```
</CodeGroup>

**Response includes composed content:**

```json theme={null}
{
  "id": "sysprompt_xyz",
  "name": "Support Bot",
  "composedContent": "You are a support agent. Respond warmly..."
}
```

***

## Attach to Model

<CodeGroup>
  ```bash curl theme={null}
  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"}'
  ```

  ```python Python theme={null}
  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")
  ```

  ```typescript Node.js theme={null}
  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');
  ```
</CodeGroup>

***

## Versioning

Particles are automatically versioned. Updates create new versions:

<CodeGroup>
  ```bash curl theme={null}
  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."}'
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```typescript Node.js theme={null}
  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}`);
  ```
</CodeGroup>

### Pin Versions

Lock a system prompt to specific particle versions for stability:

```json theme={null}
{
  "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

| 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.

***

## Related

<CardGroup cols="2">
  <Card title="Models API" icon="cube" href="/api-reference/models">
    Attach prompts to models
  </Card>

  <Card title="Chat API" icon="comments" href="/api-reference/chat">
    Override prompts at runtime
  </Card>
</CardGroup>