Introduction
The Sahha API lets you manage user profiles, and send and receive data on demand. Explore endpoints with the API Reference, or interactively test queries in the dashboard with the Query Builder.
Getting Started
- Get an Account Token — Exchange your
clientIdandclientSecretfor an account token. - Create Profiles — Register user profiles via account token (server-side) or
appId/appSecretheaders (client-side) to receive a profile token and refresh token - Access Data — Use account tokens (server-side) or profile tokens (client-side) to retrieve data
Find your clientId and clientSecret or appId and appSecret in the Sahha Dashboard under API Keys.
1. Get an Account Token
Exchange your credentials for an account token.
curl -X POST https://sandbox-api.sahha.ai/api/v1/oauth/account/token \
-H "Content-Type: application/json" \
-d '{
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}'const response = await fetch('https://sandbox-api.sahha.ai/api/v1/oauth/account/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientId: 'your-client-id',
clientSecret: 'your-client-secret'
})
});
const { accountToken } = await response.json();import requests
response = requests.post(
'https://sandbox-api.sahha.ai/api/v1/oauth/account/token',
json={
'clientId': 'your-client-id',
'clientSecret': 'your-client-secret'
}
)
data = response.json()
account_token = data['accountToken']Response:
{
"accountToken": "eyJhbGciOiJIUzI1NiIs...",
"tokenType": "Account"
}2. Create a Profile
Register a user profile using your account token:
Just exploring?
You can also create a Sample Profile in the dashboard to explore your project with sample data.
curl -X POST https://sandbox-api.sahha.ai/api/v1/oauth/profile/register \
-H "Authorization: account your-account-token" \
-H "Content-Type: application/json" \
-d '{
"externalId": "user-123"
}'const response = await fetch('https://sandbox-api.sahha.ai/api/v1/oauth/profile/register', {
method: 'POST',
headers: {
Authorization: `account ${accountToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
externalId: 'user-123'
})
});
const { profileToken, refreshToken, expiresIn, tokenType } = await response.json();response = requests.post(
'https://sandbox-api.sahha.ai/api/v1/oauth/profile/register',
headers={'Authorization': f'account {account_token}'},
json={'externalId': 'user-123'}
)
data = response.json()
profile_token = data['profileToken']
refresh_token = data['refreshToken']Response:
{
"profileToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 86400,
"tokenType": "Profile",
"refreshToken": "hIw0LuHXHZKMD7bWV0Dl..."
}3. Retrieve Scores
Fetch health scores for a profile:
curl "https://sandbox-api.sahha.ai/api/v1/profile/score/user-123?types=activity,sleep" \
-H "Authorization: account your-account-token"const response = await fetch(
'https://sandbox-api.sahha.ai/api/v1/profile/score/user-123?types=activity,sleep',
{
headers: { Authorization: `account ${accountToken}` }
}
);
const scores = await response.json();response = requests.get(
'https://sandbox-api.sahha.ai/api/v1/profile/score/user-123',
headers={'Authorization': f'account {account_token}'},
params={'types': 'activity,sleep'}
)
scores = response.json()With a profile token, omit the externalId from the path — the token identifies the profile: /api/v1/profile/score?types=activity,sleep
Response:
[
{
"type": "activity",
"value": 72.5,
"state": "medium",
"createdAt": "2024-01-15T10:30:00Z",
"factors": []
}
]Environments
All API requests are made against one of two environments:
| Environment | Base URL | Use Case |
|---|---|---|
| Sandbox | https://sandbox-api.sahha.ai | Development, testing, and getting started |
| Production | https://api.sahha.ai | Live apps with real user data |
The examples above use the Sandbox environment. When you're ready for production, replace sandbox-api.sahha.ai with api.sahha.ai.
Authentication
Sahha uses token-based authentication. You'll work with two types of tokens depending on your use case:
| Token Type | Use Case | Header Format |
|---|---|---|
| Account Token | Server-to-server operations: create profiles, query any user's data by externalId | Authorization: account {token} |
| Profile Token | Single-user operations: query own data, update demographics | Authorization: profile {token} |
Which token should I use
- Building a backend service? Use your Account Token to manage all profiles and query data by
externalId - Building a client app? Use Profile Tokens so each user can only access their own data
Token Details
| Aspect | Details |
|---|---|
| Expiration | Tokens expire after 24 hours |
| Refresh | Use the refreshToken from registration to get a new profile token via /oauth/profile/refreshToken |
| Storage | Store tokens securely; never expose secrets in client-side code |
Endpoints Summary
Quick overview of available endpoints.
Authentication
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
| POST | /api/v1/oauth/account/token | Get account token | None (uses clientId/clientSecret) |
| POST | /api/v1/oauth/profile/register | Register profile, get profile token | Account |
| POST | /api/v1/oauth/profile/register/appId | Register profile via SDK credentials | AppId/AppSecret headers |
| POST | /api/v1/oauth/profile/token | Get profile token for existing profile | Account |
| POST | /api/v1/oauth/profile/refreshToken | Refresh profile token | Profile |
Manage Profiles
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
| GET | /api/v1/account/profile/{externalId} | Get profile by externalId | Account |
| GET | /api/v1/account/profile/search | Search profiles | Account |
| DELETE | /api/v1/profile | Delete profiles | Account |
Upload Data
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
| POST | /api/v1/profile/data/log | Post data logs | Profile |
Tags
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
| POST | /api/v1/profile/tag | Upload tags | Profile |
| GET | /api/v1/profile/tag | Get tags | Profile |
| POST | /api/v1/profile/tag/{externalId} | Upload tags by externalId | Account |
| GET | /api/v1/profile/tag/{externalId} | Get tags by externalId | Account |
Retrieve Profile Data
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
| GET | /api/v1/profile/score | Get scores | Profile |
| GET | /api/v1/profile/score/{externalId} | Get scores by externalId | Account |
| GET | /api/v1/profile/biomarker | Get biomarkers | Profile |
| GET | /api/v1/profile/biomarker/{externalId} | Get biomarkers by externalId | Account |
| GET | /api/v1/profile/archetypes | Get archetypes | Profile |
| GET | /api/v1/profile/archetypes/{externalId} | Get archetypes by externalId | Account |
| GET | /api/v1/profile/insight/trend | Get trends | Profile |
| GET | /api/v1/profile/insight/trend/{externalId} | Get trends by externalId | Account |
| GET | /api/v1/profile/insight/comparison | Get comparisons | Profile |
| GET | /api/v1/profile/insight/comparison/{externalId} | Get comparisons by externalId | Account |
Profile Metadata
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
| GET | /api/v1/profile/demographic | Get demographics | Profile |
| PUT | /api/v1/profile/demographic | Replace demographics | Profile |
| PATCH | /api/v1/profile/demographic | Update demographics | Profile |
| GET | /api/v1/profile/deviceInformation | Get device info | Profile |
| PUT | /api/v1/profile/deviceInformation | Update device info | Profile |
Common Query Parameters
| Parameter | Type | Description |
|---|---|---|
startDateTime | ISO 8601 | Filter results from this date/time |
endDateTime | ISO 8601 | Filter results until this date/time |
types | string[] | Filter by type (e.g., activity, sleep) |
categories | string[] | Filter by category |
periodicity | string | Filter by periodicity (daily, weekly) |
Response Codes
| Code | Status | Description |
|---|---|---|
200 | OK | Request successful |
201 | Created | Profile registered successfully |
204 | No Content | Request successful but no data found for the query |
400 | Bad Request | Invalid parameters, malformed request, or externalId already in use |
401 | Unauthorized | Missing, invalid, or expired token |
Handling 204 responses
A 204 response means the request was valid but there's no data yet—common for new profiles or date ranges with no activity. Don't treat this as an error.
Best Practices
- Secure your credentials — Store
clientIdandclientSecretin environment variables, never in client-side code - Handle token expiration — Tokens expire in 24 hours; implement automatic refresh logic
- Use appropriate authorization — Use account tokens server-side, profile tokens client-side
- Filter your queries — Use
startDateTimeandendDateTimeto limit response size - Handle errors gracefully — Check for
401(invalid token) and400(bad request) responses
Support
Need help? Contact support@sahha.ai or join the Slack Community.