API Reference

Complete reference for the NEXXUS REST API. All endpoints require authentication and return JSON responses.

Base URL

https://api.trustscan.io/v1

Authentication

All API requests require authentication using Bearer tokens. Include your API key in the Authorization header.

Authorization Headerhttp

Authorization: Bearer ts_live_your_api_key

API Key Types

Prefix	Environment	Description
`ts_live_`	Production	Use for production applications
`ts_test_`	Sandbox	Use for testing and development

Organization Header

For multi-organization access, include the organization ID header:

Organization Headerhttp

X-Organization-ID: org_abc123

Rate Limits

API rate limits vary by plan. When exceeded, the API returns a 429 Too Many Requests response.

Plan	Requests/Minute	Evaluations/Day
Free	10	100
Pro	60	10,000
Enterprise	300	Unlimited

Rate limit headers are included in all responses:

Rate Limit Headershttp

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1703520000
Retry-After: 30

Evaluation

Evaluate AI-generated content for trust and safety compliance.

POST/evaluate

Run a synchronous evaluation on content.

Request Body

Parameter	Type	Description
`content`required	string	The AI-generated content to evaluate
`context`	string	Optional context or prompt that generated the content
`mode`	string	Evaluation mode: INSTANT, STANDARD, or DEEP
`industry`	string	Industry for domain-specific thresholds
`evaluatorIds`	string[]	Specific evaluator IDs to run
`webhookUrl`	string	Webhook URL for async completion notification

Example Request

{
  "content": "I recommend taking 500mg of ibuprofen every 4 hours for pain relief.",
  "context": "User asked about pain medication dosage",
  "mode": "STANDARD",
  "industry": "healthcare"
}

Example Response

{
  "evaluationId": "eval_abc123xyz",
  "trustScore": 72,
  "verdict": "WARN",
  "certificationTier": "SILVER",
  "blockers": [],
  "evaluatorResults": [
    {
      "evaluatorId": "NEXUS-EVAL-SA-001",
      "name": "Content Safety",
      "verdict": "PASS",
      "score": 95,
      "issues": [],
      "parameterResults": [
        {
          "parameterId": "GAI-P-SA-001",
          "name": "Harmful Content Detection",
          "value": 0.02,
          "threshold": 0.1,
          "status": "PASS"
        }
      ],
      "processingTimeMs": 156
    },
    {
      "evaluatorId": "NEXUS-EVAL-TR-002",
      "name": "Medical Accuracy",
      "verdict": "WARN",
      "score": 65,
      "issues": [
        {
          "code": "TR-002-DOSAGE",
          "severity": "MEDIUM",
          "message": "Dosage recommendation should include weight-based guidance"
        }
      ],
      "parameterResults": [],
      "processingTimeMs": 342
    }
  ],
  "metadata": {
    "mode": "STANDARD",
    "evaluatorsRun": 12,
    "totalProcessingTimeMs": 1234,
    "timestamp": "2024-12-26T10:30:00Z"
  }
}

POST/evaluate/async

Start an asynchronous evaluation for large content or deep analysis.

Async evaluations are ideal for processing large documents or when using DEEP mode. The response includes an evaluation ID that can be polled for status.

Example Response

{
  "evaluationId": "eval_async_def456",
  "status": "PROCESSING",
  "estimatedCompletionTime": "2024-12-26T10:35:00Z",
  "statusUrl": "https://api.trustscan.io/v1/evaluate/eval_async_def456"
}

GET/evaluate/{evaluationId}

Get the status or results of an evaluation.

Path Parameters

Parameter	Type	Description
`evaluationId`required	string	The evaluation ID

Reports

Generate and retrieve evaluation reports in various formats.

GET/reports/{evaluationId}

Get a formatted report for an evaluation.

Query Parameters

Parameter	Type	Description
`format`	string	Report format: json or pdf (default: json)

Example Response (PDF)

{
  "reportId": "rpt_abc123",
  "evaluationId": "eval_abc123xyz",
  "format": "pdf",
  "url": "https://reports.trustscan.io/rpt_abc123.pdf",
  "expiresAt": "2024-12-27T10:30:00Z"
}

Systems

Manage AI systems and track their evaluation history.

GET/systems

List all AI systems for the organization.

Query Parameters

Parameter	Type	Description
`industry`	string	Filter by industry
`systemType`	string	Filter by system type
`minTrustScore`	number	Minimum trust score
`certificationTier`	string	Filter by certification tier
`limit`	number	Results per page (default: 20)
`offset`	number	Pagination offset

POST/systems

Create a new AI system.

Request Body

Parameter	Type	Description
`name`required	string	System name
`description`	string	System description
`industry`required	string	Industry classification
`systemType`required	string	Type of AI system
`metadata`	object	Additional metadata

Example Request

{
  "name": "Customer Support Bot",
  "description": "AI-powered customer support assistant",
  "industry": "retail",
  "systemType": "chatbot",
  "metadata": {
    "version": "2.1.0",
    "model": "gpt-4"
  }
}

GET/systems/{systemId}

Get details of a specific system.

Path Parameters

Parameter	Type	Description
`systemId`required	string	The system ID

PATCH/systems/{systemId}

Update a system.

All fields are optional. Only provided fields will be updated.

DELETE/systems/{systemId}

Delete a system.

Returns 204 No Content on success. This action cannot be undone.

POST/systems/{systemId}/evaluate

Run an evaluation for a specific system.

Evaluations run against a system are automatically tracked in the system's history.

GET/systems/{systemId}/history

Get evaluation history for a system.

Example Response

{
  "systemId": "sys_abc123",
  "evaluations": [
    {
      "evaluationId": "eval_001",
      "trustScore": 92,
      "verdict": "PASS",
      "certificationTier": "GOLD",
      "timestamp": "2024-12-26T10:00:00Z"
    },
    {
      "evaluationId": "eval_002",
      "trustScore": 85,
      "verdict": "PASS",
      "certificationTier": "SILVER",
      "timestamp": "2024-12-25T15:30:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Webhooks

Receive real-time notifications when evaluations complete or when important events occur.

Webhook Events

Event	Description
`evaluation.completed`	Evaluation finished successfully
`evaluation.failed`	Evaluation encountered an error
`system.threshold_breach`	System trust score dropped below threshold
`certification.changed`	System certification tier changed

Webhook Payload

Example Webhook Payloadjson

{
  "id": "evt_abc123",
  "type": "evaluation.completed",
  "timestamp": "2024-12-26T10:30:00Z",
  "data": {
    "evaluationId": "eval_abc123xyz",
    "systemId": "sys_abc123",
    "trustScore": 92,
    "verdict": "PASS",
    "certificationTier": "GOLD"
  }
}

Webhook Signature

Verify webhook authenticity using the X-NEXXUS-Signature header:

Signature Verification (Python)python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Error Codes

The API uses standard HTTP status codes and returns error details in JSON format.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Content field is required",
    "details": {
      "field": "content",
      "reason": "missing_required"
    }
  }
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`204`	No Content (successful deletion)
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource does not exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Codes

Code	Description
`AUTHENTICATION_ERROR`	Invalid or expired API key
`VALIDATION_ERROR`	Request body validation failed
`RATE_LIMIT_ERROR`	Rate limit exceeded
`QUOTA_EXCEEDED`	Monthly evaluation quota exceeded
`EVALUATION_FAILED`	Evaluation processing failed
`RESOURCE_NOT_FOUND`	Requested resource not found
`PERMISSION_DENIED`	User lacks required permissions

API Reference

Authentication

API Key Types

Organization Header

Rate Limits

Evaluation

Request Body

Example Request

Example Response

Example Response

Path Parameters

Reports

Query Parameters

Example Response (PDF)

Systems

Query Parameters

Request Body

Example Request

Path Parameters

Example Response

Webhooks

Webhook Events

Webhook Payload

Webhook Signature

Error Codes

Error Response Format

HTTP Status Codes

Error Codes

Next Steps

Python SDK

JavaScript SDK