OpenVoice API Documentation

Getting Started

Welcome to the OpenVoice API! This API allows you to programmatically log communication usage, retrieve statistics, and manage user profiles.

API Access Requirements

API access is available to all registered users. Create a free account to get started.

Base URL

https://aac.steinmetz.ltd/api/v1

Authentication

All API requests require authentication using an API key. You can generate API keys from your account dashboard.

Include your API key in requests using either:

Header (recommended): X-API-Key: your_api_key_here
Query parameter: ?api_key=your_api_key_here

curl -H "X-API-Key: aac_your_api_key_here" \
  https://aac.steinmetz.ltd/api/v1/health
            

Secure Your API Key

Never share your API key publicly or commit it to version control. Treat it like a password.

API Key Management

Manage your API keys through these endpoints. These endpoints use JWT authentication (not API key).

GET /api/keys

List all your API keys

curl -H "Authorization: Bearer your_jwt_token" \
  https://aac.steinmetz.ltd/api/keys
                

POST /api/keys

Create a new API key

Parameter	Type	Required	Description
name	string	Required	Friendly name for the API key
expiresAt	datetime	Optional	Expiration date (null for no expiration)
rateLimitPerHour	integer	Optional	Requests per hour limit (default: 1000)

curl -X POST \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "rateLimitPerHour": 5000
  }' \
  https://aac.steinmetz.ltd/api/keys
                

DELETE /api/keys/:id

Delete an API key

curl -X DELETE \
  -H "Authorization: Bearer your_jwt_token" \
  https://aac.steinmetz.ltd/api/keys/123
                

Core API Endpoints

These endpoints require API key authentication via the X-API-Key header.

GET /api/v1/health

Check API health and verify your API key

curl -H "X-API-Key: aac_your_api_key" \
  https://aac.steinmetz.ltd/api/v1/health
                

Response:

{
  "success": true,
  "message": "API is operational",
  "apiKeyName": "Production API Key",
  "timestamp": "2025-01-01T12:00:00.000Z"
}
                

GET /api/v1/profile

Get user profile information

curl -H "X-API-Key: aac_your_api_key" \
  https://aac.steinmetz.ltd/api/v1/profile
                

Response:

{
  "success": true,
  "data": {
    "id": 123,
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "settings": {
      "speechRate": 1,
      "fontSize": "medium"
    }
  }
}
                

POST /api/v1/log/communication

Log communication button usage

Parameter	Type	Required	Description
buttonText	string	Required	The text of the communication button
category	string	Optional	Category (emotions, needs, actions, etc.)
sessionId	string	Optional	Session identifier for grouping

curl -X POST \
  -H "X-API-Key: aac_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "buttonText": "Happy",
    "category": "emotions",
    "sessionId": "session_123"
  }' \
  https://aac.steinmetz.ltd/api/v1/log/communication
                

POST /api/v1/log/sentence

Log sentence builder usage

Parameter	Type	Required	Description
sentence	string	Required	The complete sentence
words	array	Optional	Array of words used
duration	integer	Optional	Time taken in milliseconds
sessionId	string	Optional	Session identifier

curl -X POST \
  -H "X-API-Key: aac_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sentence": "I want water please",
    "words": ["I", "want", "water", "please"],
    "duration": 5000,
    "sessionId": "session_123"
  }' \
  https://aac.steinmetz.ltd/api/v1/log/sentence
                

GET /api/v1/logs

Retrieve usage logs

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 50, max: 500)
action	string	Filter by action type
startDate	datetime	Filter from date
endDate	datetime	Filter to date

curl -H "X-API-Key: aac_your_api_key" \
  "https://aac.steinmetz.ltd/api/v1/logs?page=1&limit=100&action=communication_button_used"
                

GET /api/v1/stats

Get usage statistics and analytics

Parameter	Type	Description
days	integer	Number of days to analyze (default: 30, max: 365)

curl -H "X-API-Key: aac_your_api_key" \
  "https://aac.steinmetz.ltd/api/v1/stats?days=30"
                

Response:

{
  "success": true,
  "data": {
    "period": {
      "days": 30,
      "startDate": "2024-12-01T00:00:00.000Z",
      "endDate": "2025-01-01T00:00:00.000Z"
    },
    "totalUsage": 1542,
    "usageByAction": [
      { "action": "communication_button_used", "count": 985 },
      { "action": "sentence_built", "count": 557 }
    ],
    "topButtons": [
      { "button": "Happy", "count": 125 },
      { "button": "Water", "count": 98 }
    ],
    "dailyUsage": [
      { "date": "2024-12-01", "count": 42 },
      { "date": "2024-12-02", "count": 38 }
    ]
  }
}
                

Rate Limits

API requests are subject to rate limiting to ensure fair usage:

Default limit: 1,000 requests per hour
Custom limits: Can be configured per API key up to 10,000 requests/hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1672531200
            

If you exceed your rate limit, you'll receive a 429 status code:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 3600
}
            

Error Handling

The API uses standard HTTP status codes:

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

All errors return a JSON response with details:

{
  "error": "Error type",
  "message": "Detailed error message"
}
            

Support

If you need help with the API:

Email: scott@steinmetz.ltd
Documentation: This page
Status: Check https://aac.steinmetz.ltd/api/health