⚠️ API Endpoints Not Yet Active
The API endpoints documented below are currently in development and not yet active. This documentation serves as a preview of the comprehensive RESTful API that will be available for AIActOS.
To see how AIActOS can help your organization and explore the platform capabilities, please and we'll show you what's possible with our platform.
Complete API reference for AIActOS. All endpoints will be versioned under /api/v1.
Comprehensive RESTful API with support for authentication, organizations, projects, assessments, documents, GitHub integration, webhooks, and more. Use API keys for programmatic access or JWT tokens for user authentication.
Create an API key from your organization settings. Store it securely - you'll only see it once.
Include your API key in the Authorization header: Authorization: Bearer YOUR_API_KEY
All endpoints are versioned under /api/v1. Use standard HTTP methods.
Responses are JSON formatted. Check status codes and handle errors appropriately.
curl -X POST https://api.aiactos.com/api/v1/organizations/ORG_ID/projects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My AI Project",
"description": "Compliance tracking for AI system"
}'API keys provide programmatic access to the AIActOS API. They are scoped to specific organizations and can have custom permissions.
Header format:
Authorization: Bearer ak_live_abc123def456...JWT tokens are issued after user authentication (login/signup). They expire after a set period and can be refreshed.
Header format:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Refresh tokens allow you to obtain new access tokens without re-authenticating. Use the /api/v1/auth/refresh endpoint.
To ensure fair usage and system stability, the AIActOS API implements rate limiting. Limits vary by endpoint and authentication method.
100
requests per minute
For authenticated users
1000
requests per minute
For API key authentication
200
requests per second
Short-term burst limit
Every API response includes rate limit information in headers:
X-RateLimit-Limit: 100Maximum requests allowed
X-RateLimit-Remaining: 95Requests remaining in window
X-RateLimit-Reset: 1640995200Unix timestamp when limit resets
When you exceed the rate limit, you'll receive a 429 status code. Implement exponential backoff and retry logic:
// Example retry logic
async function makeRequestWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
continue;
}
return response;
}
throw new Error('Max retries exceeded');
}The AIActOS API uses standard HTTP status codes and returns detailed error information in JSON format.
Invalid request parameters or malformed JSON
Missing or invalid authentication credentials
Valid credentials but insufficient permissions
Requested resource does not exist
Resource conflict (e.g., duplicate email)
Validation errors in request data
Rate limit exceeded
Server-side error occurred
Service temporarily unavailable
All error responses follow a consistent structure:
{
"error": {
"code": 400,
"message": "Validation failed",
"details": [
{
"field": "email",
"message": "Invalid email format"
},
{
"field": "password",
"message": "Password must be at least 8 characters"
}
],
"requestId": "req_abc123",
"timestamp": "2024-01-01T00:00:00.000Z"
}
}Don't assume 200 OK - handle all possible status codes
Include requestId in error logs for easier debugging
Retry on 5xx errors with exponential backoff
Display field-specific errors to users when available
async function handleApiRequest(url, options) {
try {
const response = await fetch(url, options);
const data = await response.json();
if (!response.ok) {
// Handle different error types
switch (response.status) {
case 400:
console.error('Validation error:', data.error.details);
break;
case 401:
// Refresh token or redirect to login
await refreshAuthToken();
break;
case 403:
console.error('Insufficient permissions');
break;
case 429:
// Implement rate limit handling
const retryAfter = response.headers.get('Retry-After');
await delay(parseInt(retryAfter) * 1000);
return handleApiRequest(url, options);
case 500:
case 503:
// Retry with exponential backoff
throw new Error('Server error - retry later');
default:
console.error('Unexpected error:', data);
}
throw new Error(data.error.message);
}
return data;
} catch (error) {
console.error('Request failed:', error);
throw error;
}
}Subscribe to real-time events to stay informed about changes in your projects, assessments, and documents.
assessment.completedTriggered when an assessment finishes processing
Payload Structure:
{
"assessmentId": "string",
"projectId": "string",
"status": "completed",
"complianceScore": "number",
"completedAt": "ISO 8601 timestamp"
}assessment.failedTriggered when an assessment fails
Payload Structure:
{
"assessmentId": "string",
"projectId": "string",
"status": "failed",
"error": "string",
"failedAt": "ISO 8601 timestamp"
}document.approvedTriggered when a document is approved
Payload Structure:
{
"documentId": "string",
"projectId": "string",
"type": "string",
"approvedBy": "string",
"approvedAt": "ISO 8601 timestamp"
}document.updatedTriggered when a document is updated
Payload Structure:
{
"documentId": "string",
"projectId": "string",
"version": "number",
"updatedAt": "ISO 8601 timestamp"
}project.createdTriggered when a new project is created
Payload Structure:
{
"projectId": "string",
"organizationId": "string",
"name": "string",
"createdAt": "ISO 8601 timestamp"
}scan.completedTriggered when a GitHub code scan completes
Payload Structure:
{
"scanId": "string",
"projectId": "string",
"repositoryId": "number",
"findings": "array",
"completedAt": "ISO 8601 timestamp"
}All webhook payloads are signed with HMAC SHA-256. Verify the signature to ensure the request is from AIActOS:
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(JSON.stringify(payload)).digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(digest)
);
}
// In your webhook handler
const signature = request.headers['x-aiactos-signature'];
const isValid = verifyWebhookSignature(request.body, signature, webhookSecret);
if (!isValid) {
return response.status(401).json({ error: 'Invalid signature' });
}Use our official SDKs to integrate AIActOS into your applications quickly and easily. All SDKs are open source and actively maintained.
Official SDK for Node.js and browser environments
Install:
npm install @aiactos/sdkFeatures:
Python SDK for server-side and CLI applications
Install:
pip install aiactosFeatures:
Go SDK for high-performance applications
Install:
go get github.com/aiactos/go-sdkFeatures:
Ruby SDK with elegant syntax
Install:
gem install aiactosFeatures:
import { AIActOS } from '@aiactos/sdk';
const client = new AIActOS({
apiKey: process.env.AIACTOS_API_KEY
});
// Create a project
const project = await client.projects.create({
organizationId: 'org_123',
name: 'My AI Project',
description: 'Compliance tracking'
});
// Run an assessment
const assessment = await client.assessments.create({
projectId: project.id,
regulationPackId: 'eu-ai-act-v1'
});
// Get results
const results = await client.assessments.get(assessment.id);
console.log(`Compliance Score: ${results.complianceScore}%`);Community SDKs: We welcome community contributions! If you'd like to create an SDK for another language, check out our GitHub organization for guidelines.
All API requests should be made to:
https://api.aiactos.comFor authentication, include the JWT token or API key in the Authorization header:
Authorization: Bearer <your-token-or-api-key>The current API version is v1. All endpoints are versioned under /api/v1.
We maintain backward compatibility within major versions. When breaking changes are introduced, a new version will be released with deprecation notices for the previous version.