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

# Particles API

> Create modular, reusable system prompt components. Particles enable versioned, composable AI behavior configuration.

## Categories

Particles are organized into five categories, composed in this order:

| Priority | Category      | Purpose             | Example                            |
| -------- | ------------- | ------------------- | ---------------------------------- |
| 1        | `role`        | Identity            | "You are a customer support agent" |
| 2        | `tone`        | Communication style | "Be professional and empathetic"   |
| 3        | `guardrails`  | Safety constraints  | "Never share internal docs"        |
| 4        | `constraints` | Operational limits  | "Keep responses under 500 words"   |
| 5        | `format`      | Output formatting   | "Use markdown with headers"        |

***

## Quick Start

<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": "Professional Support Agent",
      "category": "role",
      "content": "You are a professional customer support agent. Always be helpful, empathetic, and solution-oriented.",
      "description": "Primary support persona"
    }'
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.post(
      "https://api.cuadra.ai/v1/particles",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
      json={
          "name": "Professional Support Agent",
          "category": "role",
          "content": "You are a professional customer support agent...",
          "description": "Primary support persona"
      }
  )
  print(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: 'Professional Support Agent',
      category: 'role',
      content: 'You are a professional customer support agent...',
      description: 'Primary support persona'
    })
  });
  const particle = await response.json();
  ```
</CodeGroup>

***

## Automatic Versioning

Content changes create a new version automatically:

```bash theme={null}
# Version 1
curl -X POST /v1/particles -d '{"content": "You are a support agent."}'

# Update → Version 2
curl -X PUT /v1/particles/part_abc -d '{"content": "You are a professional support agent."}'
```

System prompts using unpinned particles automatically get the latest version.

***

## Token Budget Guidelines

Keep particles concise for cost efficiency:

| Category    | Recommended        | Why                     |
| ----------- | ------------------ | ----------------------- |
| Role        | 50-100 tokens      | Core identity only      |
| Tone        | 25-50 tokens       | Style, not examples     |
| Guardrails  | 50-150 tokens      | Critical safety rules   |
| Constraints | 25-75 tokens       | Specific limits         |
| Format      | 25-50 tokens       | Structure only          |
| **Total**   | **175-425 tokens** | Leaves room for context |

<Tip>
  Use `GET /v1/particles/{id}` to see `tokenCount` for each particle. The compose endpoint shows total token usage.
</Tip>

***

## Related

<CardGroup cols={2}>
  <Card title="System Prompts API" icon="sliders" href="/api-reference/system-prompts">
    Compose particles into prompts
  </Card>

  <Card title="Particles Guide" icon="book" href="/guides/particles">
    Best practices
  </Card>
</CardGroup>