Skip to main content

​
Base URL

All API requests should be made to: 
https://api.stardex.ai
For example, to access the /v1/persons endpoint, you would make a request to: 
https://api.stardex.ai/v1/persons

​
Authentication

All API endpoints require authentication using Bearer tokens in the Authorization header. Add your API key as follows: 
Authorization: Bearer your_api_key_here
You can get your API key from the Stardex Settings.

​
Response Format

All API endpoints follow a consistent response format:

​
Successful Responses

{
  "success": true,
  "data": object  // Response data
}
For paginated responses: 
{
  "success": true,
  "data": array,
  "meta": {
    "total": number,
    "offset": number,
    "limit": number
  }
}

​
Example Successful Response

{
  "success": true,
  "data": {
    "id": "123",
    "name": "John Doe"
    // ... other fields
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": string,
    "message": string,
  }
}

​
Example Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired"
  }
}
Common HTTP Status Codes:
  • 200: Operation completed successfully
  • 400: Invalid request or missing fields
  • 401: Missing or invalid API key
  • 403: Forbidden - insufficient permissions
  • 404: Resource not found
  • 429: Rate limit exceeded
  • 500: Unexpected server error

​
Rate Limits

API requests are rate-limited using a sliding window of 60 requests per minute per API key. If you exceed the limit, the API will respond with a 429 Too Many Requests status code.
Rate limits apply per API key. Each key has its own independent counter.

​
Rate Limit Headers

Every API response includes headers to help you track your current usage:
HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed per minute
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the current window resets

​
Rate Limit Exceeded Response

When the rate limit is exceeded, the API returns a 429 status code with a Retry-After header: 
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "retry_after_seconds": 30,
    "limit": 60,
    "reset_at": 1717027200
  }
}
FieldDescription
retry_after_secondsSeconds to wait before making another request
limitYour rate limit (requests per minute)
reset_atUnix timestamp (seconds) when the window resets

​
Best Practices

  • Check rate limit headers on every response to monitor your usage.
  • Implement exponential backoff when you receive a 429 response — wait for the retry_after_seconds value before retrying.
  • Spread requests over time rather than sending them in bursts to avoid hitting the limit.
  • Cache responses where possible to reduce the total number of API calls.