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

> Compose particles into complete AI behavior configurations. Manage versioned, modular system prompts.

## Quick Start

### 1. Create System 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": "Customer Support",
      "description": "Professional support with safety guardrails"
    }'
  ```

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

  response = httpx.post(
      "https://api.cuadra.ai/v1/system-prompts",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
      json={"name": "Customer Support", "description": "Professional support with safety guardrails"}
  )
  system_prompt = response.json()
  print(f"Created: {system_prompt['id']}")
  ```

  ```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: 'Customer Support',
      description: 'Professional support with safety guardrails'
    })
  });
  const systemPrompt = await response.json();
  console.log(`Created: ${systemPrompt.id}`);
  ```
</CodeGroup>

### 2. Add Particles

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.cuadra.ai/v1/system-prompts/sp_abc123/particles \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"particleId": "part_role_001", "order": 1}'
  ```

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

  response = httpx.post(
      "https://api.cuadra.ai/v1/system-prompts/sp_abc123/particles",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
      json={"particleId": "part_role_001", "order": 1}
  )
  print("Particle added")
  ```

  ```typescript Node.js theme={null}
  await fetch('https://api.cuadra.ai/v1/system-prompts/sp_abc123/particles', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ particleId: 'part_role_001', order: 1 })
  });
  console.log('Particle added');
  ```
</CodeGroup>

### 3. View Composed Prompt

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

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

  response = httpx.get(
      "https://api.cuadra.ai/v1/system-prompts/sp_abc123/compose",
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  composed = response.json()
  print(f"Total tokens: {composed['totalTokens']}")
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cuadra.ai/v1/system-prompts/sp_abc123/compose', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  const composed = await response.json();
  console.log(`Total tokens: ${composed.totalTokens}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "composedPrompt": "You are a professional customer support agent...",
  "totalTokens": 150,
  "particles": [
    { "id": "part_abc", "category": "role", "version": 2, "tokenCount": 25 }
  ]
}
```

***

## Version Pinning

| Environment | Strategy | Why                                  |
| ----------- | -------- | ------------------------------------ |
| Development | Unpinned | Always test latest particle versions |
| Staging     | Unpinned | Catch issues before production       |
| Production  | Pinned   | Stability and predictability         |

To pin a particle to a specific version:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.cuadra.ai/v1/system-prompts/sp_abc123/particles \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "particleId": "part_xyz789",
      "particleVersionId": "pv_v2"
    }'
  ```

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

  response = httpx.post(
      "https://api.cuadra.ai/v1/system-prompts/sp_abc123/particles",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
      json={"particleId": "part_xyz789", "particleVersionId": "pv_v2"}
  )
  print("Pinned particle added")
  ```

  ```typescript Node.js theme={null}
  await fetch('https://api.cuadra.ai/v1/system-prompts/sp_abc123/particles', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ particleId: 'part_xyz789', particleVersionId: 'pv_v2' })
  });
  console.log('Pinned particle added');
  ```
</CodeGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Particles API" icon="atom" href="/api-reference/particles">
    Create reusable prompt components
  </Card>

  <Card title="System Prompts Guide" icon="book" href="/guides/system-prompts">
    Best practices
  </Card>
</CardGroup>