Skip to main content
POST
/
v1
/
particles
Create Particle
curl --request POST \
  --url https://api.cuadra.ai/v1/particles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "category": "tone",
  "content": "<string>",
  "description": "Sets a professional communication style",
  "enabled": true
}
'
{
  "id": "<string>",
  "name": "<string>",
  "category": "tone",
  "isSystem": true,
  "enabled": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "description": "Sets professional tone",
  "currentVersion": 3,
  "tokenCount": 25,
  "content": "Maintain a professional tone.",
  "versions": [
    {
      "id": "<string>",
      "version": 123,
      "tokenCount": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "content": "You are a helpful assistant.",
      "createdBy": "user_xyz789"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

JWT token from Stytch B2B authentication (magic link, SSO, or M2M)

Headers

​
Idempotency-Key
string | null

Body

application/json

Request schema for creating a particle.

​
name
string
required

Human-readable name for the particle

Required string length: 1 - 255
Example:

"Professional Tone"

​
category
enum<string>
required

Particle category (role, tone, guardrails, constraints, format)

Available options:
role,
tone,
guardrails,
constraints,
format
Example:

"tone"

​
content
string
required

The prompt content for this particle

Required string length: 1 - 50000
Example:

"Maintain a professional, courteous tone in all responses."

​
description
string | null

Optional description of the particle's purpose

Maximum string length: 1000
Example:

"Sets a professional communication style"

​
enabled
boolean
default:true

Whether the particle is active

Example:

true

Response

Successful Response

Response schema for particle. Content visibility is controlled by is_system flag: - System particles: content hidden (MOAT protection) - Organization particles: content visible to org members

​
id
string
required

Unique particle identifier

Example:

"part_abc123"

​
name
string
required

Human-readable name

Example:

"Professional Tone"

​
category
enum<string>
required

Particle category

Available options:
role,
tone,
guardrails,
constraints,
format
Example:

"tone"

​
isSystem
boolean
required

Whether this is a system-managed particle

Example:

false

​
enabled
boolean
required

Whether the particle is active

Example:

true

​
createdAt
string<date-time>
required

Timestamp when the particle was created

Example:

"2024-01-15T10:30:00Z"

​
updatedAt
string<date-time>
required

Timestamp when the particle was last updated

Example:

"2024-01-15T14:45:00Z"

​
description
string | null

Particle description

Example:

"Sets professional tone"

​
currentVersion
integer | null

Current version number (derived from current_version)

Example:

3

​
tokenCount
integer | null

Token count of current version

Example:

25

​
content
string | null

Current content (hidden for system particles)

Example:

"Maintain a professional tone."

​
versions
ParticleVersionOut · object[] | null

Version history (when expanded)