Onboarding API

Onboarding state machine and zip upload endpoints

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"

Example Response

{
  "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"

Example Response

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

Onboarding State Machine

State Descriptions

State	Description	User Action
EXTENSION_INSTALL	Initial state	Install browser extension
DATA_COLLECTION	Extension ready	Export and upload data
PROCESSING	Data being processed	Wait for completion
COMPLETE	Onboarding finished	Access 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

Related Endpoints

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).