API Documentation

Complete reference for the Acaysia REST API. Integrate process data, control outputs, and analytics into your systems.

API Reference

Overview

The Acaysia API provides programmatic access to process data, control system status, and analytics. The API follows REST conventions and returns JSON responses.

Base URL

https://api.acaysia.com/v1

For on-premise deployments, replace with your local edge device address:

https://<edge-device-ip>:8443/api/v1

API Versioning

The API version is included in the URL path. The current version is v1. When we release breaking changes, we'll increment the version number while maintaining support for previous versions.

Authentication

All API requests require authentication using API keys or OAuth 2.0 tokens.

API Key Authentication

Include your API key in the request header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.acaysia.com/v1/status

Obtaining API Keys

  1. Log in to the Acaysia Dashboard
  2. Navigate to Settings → API Keys
  3. Click "Generate New Key"
  4. Copy and securely store the key (it won't be shown again)
Security: Never expose API keys in client-side code or public repositories. Use environment variables or secure secret management.

Key Permissions

Permission Level Capabilities
Read-Only GET requests for process data and status
Standard Read-only + model configuration updates
Full Access All operations including control actions

Endpoints Overview

Endpoint Method Description
/status GET System status and health
/process/data GET Current process variable values
/process/history GET Historical process data
/control/mode GET, PUT Control mode (shadow/advisory/closed-loop)
/control/recommendations GET Current control recommendations
/models GET, POST Model management
/models/{id}/predictions GET Model predictions
/alarms GET Active and historical alarms
/events GET System events and audit log

Process Data API

Get Current Values

Retrieve the latest values for all configured process variables.

GET /process/data

Response

{
  "timestamp": "2025-01-15T14:30:00Z",
  "variables": [
    {
      "name": "reactor_temperature",
      "value": 125.4,
      "unit": "°C",
      "quality": "good",
      "timestamp": "2025-01-15T14:30:00Z"
    },
    {
      "name": "reactor_pressure",
      "value": 2.45,
      "unit": "bar",
      "quality": "good",
      "timestamp": "2025-01-15T14:30:00Z"
    },
    {
      "name": "feed_flow_rate",
      "value": 150.2,
      "unit": "L/min",
      "quality": "good",
      "timestamp": "2025-01-15T14:30:00Z"
    }
  ]
}

Get Historical Data

Retrieve historical process data for analysis.

GET /process/history?variables=reactor_temperature,reactor_pressure
                    &start=2025-01-15T00:00:00Z
                    &end=2025-01-15T12:00:00Z
                    &resolution=1m

Query Parameters

Parameter Type Description
variables string Comma-separated list of variable names
start ISO 8601 Start time for data retrieval
end ISO 8601 End time for data retrieval
resolution string Data resolution: 1s, 10s, 1m, 5m, 1h

Response

{
  "start": "2025-01-15T00:00:00Z",
  "end": "2025-01-15T12:00:00Z",
  "resolution": "1m",
  "data": {
    "reactor_temperature": {
      "timestamps": ["2025-01-15T00:00:00Z", "2025-01-15T00:01:00Z", ...],
      "values": [120.1, 120.3, 120.5, ...],
      "unit": "°C"
    },
    "reactor_pressure": {
      "timestamps": ["2025-01-15T00:00:00Z", "2025-01-15T00:01:00Z", ...],
      "values": [2.41, 2.42, 2.43, ...],
      "unit": "bar"
    }
  }
}

Control API

Get Current Mode

GET /control/mode

Response

{
  "mode": "advisory",
  "since": "2025-01-10T08:00:00Z",
  "available_modes": ["shadow", "advisory", "closed_loop"],
  "can_transition_to": ["shadow", "closed_loop"]
}

Change Control Mode

PUT /control/mode

{
  "mode": "closed_loop",
  "confirm": true
}
Caution: Changing to closed-loop mode enables automatic control. Ensure all safety checks are complete and appropriate personnel are notified.

Get Recommendations

Retrieve current control recommendations (available in all modes).

GET /control/recommendations

Response

{
  "timestamp": "2025-01-15T14:30:00Z",
  "horizon_minutes": 30,
  "recommendations": [
    {
      "variable": "coolant_valve",
      "current_value": 45.0,
      "recommended_value": 52.0,
      "unit": "%",
      "confidence": 0.92,
      "reasoning": "Anticipating exothermic peak in 8 minutes"
    },
    {
      "variable": "agitator_speed",
      "current_value": 150,
      "recommended_value": 150,
      "unit": "RPM",
      "confidence": 0.95,
      "reasoning": "Maintain current mixing rate"
    }
  ],
  "predicted_outcomes": {
    "temperature_deviation": 0.3,
    "energy_savings": 2.1,
    "batch_time_reduction": 1.5
  }
}

Models API

List Models

GET /models

Response

{
  "models": [
    {
      "id": "model_abc123",
      "name": "Reactor1_Thermal",
      "type": "gray_box",
      "status": "active",
      "accuracy": 0.96,
      "last_trained": "2025-01-14T02:00:00Z",
      "training_data_points": 125000
    },
    {
      "id": "model_def456",
      "name": "Reactor1_Kinetic",
      "type": "neural_network",
      "status": "active",
      "accuracy": 0.94,
      "last_trained": "2025-01-14T02:00:00Z",
      "training_data_points": 125000
    }
  ]
}

Get Model Predictions

GET /models/{model_id}/predictions?horizon=30m

Response

{
  "model_id": "model_abc123",
  "generated_at": "2025-01-15T14:30:00Z",
  "horizon_minutes": 30,
  "predictions": {
    "reactor_temperature": {
      "timestamps": ["2025-01-15T14:31:00Z", "2025-01-15T14:32:00Z", ...],
      "values": [125.6, 125.9, 126.3, ...],
      "confidence_lower": [125.2, 125.4, 125.6, ...],
      "confidence_upper": [126.0, 126.4, 127.0, ...]
    }
  }
}

Webhooks

Configure webhooks to receive real-time notifications for events.

Supported Events

  • alarm.triggered - New alarm activated
  • alarm.cleared - Alarm condition cleared
  • mode.changed - Control mode changed
  • fallback.activated - System fell back to PID
  • model.retrained - Model retraining completed

Webhook Payload

{
  "event": "alarm.triggered",
  "timestamp": "2025-01-15T14:35:00Z",
  "data": {
    "alarm_id": "alm_12345",
    "name": "High Temperature",
    "variable": "reactor_temperature",
    "value": 182.5,
    "limit": 180.0,
    "severity": "high"
  }
}

Configure Webhooks

POST /webhooks

{
  "url": "https://your-server.com/acaysia-webhook",
  "events": ["alarm.triggered", "fallback.activated"],
  "secret": "your-webhook-secret"
}

Error Handling

The API uses standard HTTP status codes and returns detailed error messages.

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'resolution' parameter must be one of: 1s, 10s, 1m, 5m, 1h",
    "details": {
      "parameter": "resolution",
      "provided_value": "2m"
    }
  }
}

Common Error Codes

HTTP Status Error Code Description
400 invalid_parameter Request parameter is invalid
401 unauthorized Invalid or missing API key
403 forbidden API key lacks required permissions
404 not_found Requested resource does not exist
429 rate_limited Too many requests
500 internal_error Server error

Rate Limits

API requests are rate-limited to ensure fair usage and system stability.

Endpoint Category Rate Limit
Process data (current) 60 requests/minute
Historical data 10 requests/minute
Control operations 10 requests/minute
Model operations 30 requests/minute

Rate limit status is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705329600

SDK Libraries

Official SDK libraries are available for common languages:

Need help? Contact our developer support at founders@acaysia.com.

Start Building

Get your API key and start integrating with Acaysia today.

Get API Access