Skip to main content

​
Stages

Stages represent different phases or states in a user’s journey through your system. They enable you to track progression, trigger stage-specific behaviors, and provide contextual experiences.

​
List Stages

GET /stages

Returns a list of all stages defined in your workspace.

​
Response

​
message
string
Success message
​
data
array
Array of stage objects

​
Get Stage

GET /stages/:stage_id

Returns detailed information about a specific stage.
​
:stage_id
string
required
Stage unique identifier

​
Create Stage

POST /stages

Creates a new stage definition.

​
Request Body

​
string
required
Stage name (3-100 characters)
​
string
Stage description
​
object
Custom metadata for the stage

​
Update Stage

PUT /stages/:stage_id

Updates an existing stage definition.
​
:stage_id
string
required
Stage unique identifier

​
Request Body

​
string
Stage name (3-100 characters)
​
string
Stage description
​
object
Custom metadata for the stage

​
Assign Stage to Identity

POST /identity/:identity_id/stage

Assigns a stage to an identity, tracking their current position in the journey.
See Identity API for details.

​
How Stages Work

  1. Define Stages - Create stage definitions for your user journey
  2. Assign to Identities - Set identities to specific stages
  3. Use in Prompts - Reference current stage in assistant instructions
  4. Track Progression - Monitor how users move through stages

​
Stage Examples

Common stage patterns:
  • Onboarding: welcome, profile_setup, tutorial, onboarding_complete
  • Product: browsing, considering, purchased, active_user
  • Support: needs_help, in_conversation, resolved, escalated

​
Using Stages in Prompts

Reference the current stage in assistant instructions: 
You are a helpful assistant. The user is currently in the {{identity.stage}} stage.
{{#if identity.stage == "onboarding"}}
  Focus on welcoming them and explaining key features.
{{/if}}

​
Examples

​
List Stages

curl -X GET https://api.plati.ai/stages \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Create Stage

curl -X POST https://api.plati.ai/stages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "onboarding_complete",
    "description": "User has completed onboarding",
    "metadata": {
      "requires_action": false,
      "next_stage": "active_user"
    }
  }'

​
Get Stage

curl -X GET https://api.plati.ai/stages/onboarding_complete \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Update Stage

curl -X PUT https://api.plati.ai/stages/onboarding_complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding Complete",
    "description": "User has completed the onboarding process"
  }'

​
Next Steps

Identity

Assign stages to identities

Prompt Engineering

Use stages in prompts

Core Concepts

Learn about stage management