API Overview

Introduction to the OnboardSync REST API

Base URL

All API requests should be made to:

https://onboardsync.vercel.app/api

Authentication

The OnboardSync API uses two types of authentication:

1. Secret Keys (for Mobile SDKs)

Mobile SDKs use project-specific secret keys that are safe for client-side usage:

X-Project-Id: your-project-id
X-Secret-Key: your-secret-key

2. User Authentication (for Dashboard)

Dashboard operations use Supabase authentication with JWT tokens:

Authorization: Bearer YOUR_JWT_TOKEN

Secret keys are found in your project’s API Keys section in the dashboard. They are designed to be used in mobile apps and only provide read access to your onboarding configuration.

Request Format

All requests should include the following headers:

Content-Type: application/json
Accept: application/json

Response Format

All responses are returned in JSON format:

{
  "success": true,
  "data": {
    // Response data
  }
}

Error responses follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

HTTP Status Codes

Status Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limiting

API requests are rate limited to ensure fair usage:

• Authenticated requests: 1000 requests per hour
• Unauthenticated requests: 100 requests per hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Pagination

List endpoints support pagination using query parameters:

GET /api/projects?page=1&limit=20

Paginated responses include metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Filtering & Sorting

Many endpoints support filtering and sorting:

# Filter by status
GET /api/flows?status=active

# Sort by created date
GET /api/flows?sort=-created_at

# Combine filters
GET /api/flows?status=active&sort=-created_at

API Endpoints

Public Endpoints

These endpoints are used by mobile SDKs with secret key authentication:

Endpoint	Description
POST /api/onboarding/resolve	Resolve which flow to show for a device
GET /api/config	Fetch project configuration
POST /api/analytics/event	Track analytics events

Management Endpoints

These endpoints require user authentication and are used for managing your onboarding flows:

Endpoint	Description
GET /api/projects	List projects
POST /api/projects	Create project
PUT /api/projects/:id	Update project
DELETE /api/projects/:id	Delete project
GET /api/flows	List flows for a project
POST /api/flows	Create flow
PUT /api/flows/:id	Update flow
DELETE /api/flows/:id	Delete flow
GET /api/screens	List screens for a flow
POST /api/screens	Create screen
PUT /api/screens/:id	Update screen
DELETE /api/screens/:id	Delete screen
GET /api/themes	List themes
POST /api/themes	Create theme
PUT /api/themes/:id	Update theme
DELETE /api/themes/:id	Delete theme
GET /api/analytics	Get analytics data
GET /api/user/api-key	Get user’s API key

Error Handling

Common Error Codes

Error Code	Description
INVALID_PROJECT	Project ID is invalid or doesn’t exist
INVALID_FLOW	Flow ID is invalid or doesn’t exist
MISSING_PARAMETER	Required parameter is missing
INVALID_PARAMETER	Parameter value is invalid
UNAUTHORIZED	Authentication failed
RATE_LIMITED	Too many requests

Error Response Example

{
  "success": false,
  "error": {
    "code": "INVALID_PROJECT",
    "message": "Project with ID 'proj_123' not found",
    "details": {
      "projectId": "proj_123"
    }
  }
}

Versioning

The API is versioned through the URL path. The current version is v1 (implied when not specified).

Future versions will be accessible at:

https://onboardsync.vercel.app/api/v2

SDK Integration

The OnboardSync SDKs handle API communication automatically. You typically won’t need to make direct API calls unless you’re:

• Building a custom integration
• Creating admin tools
• Accessing advanced features
• Building server-side analytics dashboards

The SDKs handle:

• Device ID generation and persistence
• Flow resolution based on A/B test configuration
• Analytics event tracking
• Error handling and retries

Testing

For testing, create a test project in the dashboard and use its credentials. This allows you to:

• Test different flow configurations
• Verify analytics tracking
• Debug integration issues

Without affecting your production flows.

Next Steps

Authentication

Learn about API authentication

Projects API

Manage your projects

Flows API

Create and update flows

Analytics API

Access analytics data