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

> Create reusable, versioned prompt components. Particles are the building blocks for system prompts in Cuadra AI.

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

```bash theme={null}
POST /v1/particles
```

<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 Tone",
      "category": "tone",
      "content": "Communicate professionally. Use clear, concise language."
    }'
  ```

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

  ```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 Tone',
      category: 'tone',
      content: 'Communicate professionally. Use clear, concise language.'
    })
  });
  const particle = await response.json();
  ```
</CodeGroup>

### Response

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

Categories are composed in fixed order. Within each category, you control ordering via the `order` field.

***

## List Particles

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.cuadra.ai/v1/particles \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

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

  response = httpx.get(
      "https://api.cuadra.ai/v1/particles",
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  particles = response.json()["data"]
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cuadra.ai/v1/particles', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  const { data: particles } = await response.json();
  ```
</CodeGroup>

### Filter by Category

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.cuadra.ai/v1/particles?category=guardrails" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.cuadra.ai/v1/particles",
      params={"category": "guardrails"},
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cuadra.ai/v1/particles?category=guardrails', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  ```
</CodeGroup>

***

## Get Particle

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.cuadra.ai/v1/particles/particle_abc123 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

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

  response = httpx.get(
      "https://api.cuadra.ai/v1/particles/particle_abc123",
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  particle = response.json()
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc123', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  const particle = await response.json();
  ```
</CodeGroup>

### Get Specific Version

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.cuadra.ai/v1/particles/particle_abc123?version=2" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.cuadra.ai/v1/particles/particle_abc123",
      params={"version": 2},
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc123?version=2', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  ```
</CodeGroup>

***

## Update Particle

Updates create a new version automatically:

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

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

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

### Response

```json theme={null}
{
  "id": "particle_abc123",
  "name": "Professional Tone",
  "content": "Updated: Be professional and empathetic.",
  "currentVersion": 2,
  "tokenCount": 10
}
```

***

## Delete Particle

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://api.cuadra.ai/v1/particles/particle_abc123 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

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

  response = httpx.delete(
      "https://api.cuadra.ai/v1/particles/particle_abc123",
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  # Returns 204 No Content on success
  ```

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

<Warning>
  Deleting a particle affects all system prompts using it. Unlink from system prompts first.
</Warning>

***

## Version History

List all versions of a particle:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.cuadra.ai/v1/particles/particle_abc123/versions \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

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

  response = httpx.get(
      "https://api.cuadra.ai/v1/particles/particle_abc123/versions",
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  versions = response.json()["data"]
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cuadra.ai/v1/particles/particle_abc123/versions', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  const { data: versions } = await response.json();
  ```
</CodeGroup>

### Response

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

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

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

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

<CardGroup cols="2">
  <Card title="System Prompts" icon="sliders" href="/guides/system-prompts">
    Compose particles into prompts
  </Card>

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