Skip to main content

​
Overview

The onboarding system guides new users through setup with a state machine tracking progress from extension installation through data collection and processing.

​
GET /api/onboarding/state

Retrieve current onboarding state for authenticated user.

​
Authentication

Requires Directus JWT token.

​
Response

​
state
string
Current onboarding state: EXTENSION_INSTALL, DATA_COLLECTION, PROCESSING, or COMPLETE
​
userId
string
User ID from persona record

​
Example

cURL
curl http://localhost:3001/api/onboarding/state \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "state": "DATA_COLLECTION",
  "userId": "abc-123"
}

​
PATCH /api/onboarding/state

Update onboarding state for authenticated user.

​
Request Body

​
state
string
required
New state: EXTENSION_INSTALL, DATA_COLLECTION, PROCESSING, or COMPLETE

​
Response

Returns updated persona record with new onboarding state.

​
Example

cURL
curl -X PATCH http://localhost:3001/api/onboarding/state \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "COMPLETE"}'

​
POST /api/onboarding/zip-upload

Upload data export zip file for processing.

​
Authentication

Requires Directus JWT token.

​
Request Body

Multipart form data with single file field:
​
file
file
required
ZIP file containing platform data export

​
Response

​
ok
boolean
Whether upload was successful
​
jobId
string
BullMQ job ID for tracking processing
​
filePath
string
Server path where zip was stored

​
Example

cURL
curl -X POST http://localhost:3001/api/onboarding/zip-upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@/path/to/export.zip"

{
  "ok": true,
  "jobId": "onboard-job-123456",
  "filePath": "/tmp/agentx-media/onboard-abc123.zip"
}

​
Onboarding State Machine

​
State Descriptions

StateDescriptionUser Action
EXTENSION_INSTALLInitial stateInstall browser extension
DATA_COLLECTIONExtension readyExport and upload data
PROCESSINGData being processedWait for completion
COMPLETEOnboarding finishedAccess full platform

​
Content Gate Integration

The Genie AI chat enforces onboarding completion:
  • Users in EXTENSION_INSTALL or DATA_COLLECTION receive setup guidance
  • Full AI features unlock only in COMPLETE state
  • State checked on every chat request via server/endpoints/api/genieChat.js

Genie Chat

AI chat with onboarding gate enforcement

User Profile

Update user persona and profile data

​
Implementation

Source: server/endpoints/api/onboarding.js Onboarding state stored in user_personas.onboarding_state (Directus collection).

Build docs developers (and LLMs) love

Get started for freeTalk to us