API Overview

Introduction

The Semaphor API provides programmatic access to Semaphor's embedded analytics platform. With our RESTful API, you can manage dashboards, generate authentication tokens, and integrate Semaphor analytics into your applications.

Base URL

All API requests should be made to:

https://semaphor.cloud/api

Authentication

Most API endpoints require authentication using your dashboard credentials. You'll need:

• Dashboard ID: A unique identifier for your dashboard
• Dashboard Secret: A secure key for authenticating API requests

Rate Limits

The Semaphor API implements rate limiting to ensure fair usage:

• Token Generation: 100 requests per minute per dashboard
• Dashboard Operations: 1000 requests per minute per dashboard
• General API: 5000 requests per minute per account

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Response Format

All API responses are returned in JSON format with the following structure:

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation completed successfully"
}

Error responses follow this format:

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided token is invalid or expired",
    "details": {}
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 429 - Too Many Requests
• 500 - Internal Server Error

SDKs and Libraries

While you can use any HTTP client to interact with the Semaphor API, we provide official SDKs for popular languages:

• JavaScript/TypeScript: semaphor npm package
• Python: Coming soon
• Go: Coming soon

Getting Started

1. Get your credentials from the Semaphor Console
2. Generate an authentication token using the Token API
3. Start building with our Dashboard API

For detailed information about specific endpoints, see the sections below.