Start Free Trial
API

API Reference

REST API endpoints for the aissurance platform.

Base URL

All API endpoints are prefixed with /api/v1/ unless noted otherwise.

Authentication

User Authentication

JWT-based authentication using FastAPI Users. Include the access token in the Authorization header:

Authorization: Bearer <access_token>

Tenant API Key (Discovery)

For Nomyo Router discovery payloads, authenticate with the tenant’s API key:

Authorization: Bearer <AISSURANCE_KEY>

Discovery Endpoints

Receive Discovery Payload

POST /discovery/payload

Receive model inventory, endpoint registry, and telemetry data from Nomyo Router. Payload must include HMAC-SHA256 signature.

Request Body: NomyoDiscoveryPayload

  • tenant_id: string
  • models: array of NomyoModel
  • endpoints: array of endpoint objects
  • telemetry: telemetry data
  • hmac_signature: SHA-256 signature

Discovery Health Check

GET /discovery/health
GET /discovery/health/tenant/{tenant_id}

Check global or per-tenant discovery integration status.

Response:

{
  "total_connected_instances": 450,
  "success_rate": 99.8,
  "last_sync": "2026-06-01T10:30:00Z"
}

Config Report

POST /discovery/config/report

Report Nomyo Router configuration state to aissurance.

Admin Discovery Endpoints

GET  /admin/discovery/health
POST /admin/discovery/blacklist

Global discovery health status and IP/tenant key blacklist management.

Inventory Endpoints

List AI Systems

GET /inventory/systems?tenant_id={tenant_id}

Create AI System

POST /inventory/systems

Request Body:

{
  "tenant_id": "uuid",
  "name": "string",
  "description": "string",
  "use_case": "customer_service|healthcare|employment|...",
  "is_public_sector": false
}

Update AI System

PATCH /inventory/systems/{system_id}

Delete AI System

DELETE /inventory/systems/{system_id}

Classification Endpoints

Classify System

POST /classification/classify

Run the JSON rules engine against an AI system’s attributes.

Request Body:

{
  "tenant_id": "uuid",
  "ai_system_id": "uuid",
  "use_case": "string",
  "is_public_sector": false,
  "annexiii_categories": ["string"],
  "description": "string"
}

Response: ClassificationResult

  • risk_level: “unrestricted” | “limited” | “high” | “prohibited” | “gpai” | “gpai_systemic”
  • rules_matched: array of matched rule objects with clause references
  • confidence: float

List Classifications

GET /classification/results?tenant_id={tenant_id}
GET /classification/results/system/{system_id}

Rules Management

GET  /admin/rules/risk-tiers
POST /admin/rules/update

View and update the classification decision tree without code deploys.

Evidence Endpoints

List Evidence

GET /evidence?tenant_id={tenant_id}&ai_system_id={system_id}

Upload Evidence File

POST /evidence/upload

Upload file evidence with automatic Annex IV element mapping.

Submit Text Evidence

POST /evidence/text

Submit text-based evidence directly (no file upload required).

Request Body:

{
  "tenant_id": "uuid",
  "ai_system_id": "uuid",
  "element_order": 3,
  "content": "Text evidence content...",
  "file_type": "general_purpose"
}

Update Evidence Status

PATCH /evidence/{evidence_id}/status

Set verification status: pending, verified, or rejected.

Discovery Evidence

GET /evidence/discovery?tenant_id={tenant_id}

Retrieve evidence auto-generated from Nomyo Router discovery data.

Documentation Endpoints

List Documentation Items

GET /documentation?tenant_id={tenant_id}&ai_system_id={system_id}

Create Documentation Item

POST /documentation

Create structured documentation for one of the 14 Annex IV elements.

Update Documentation Item

PATCH /documentation/{item_id}

Delete Documentation Item

DELETE /documentation/{item_id}

Documents Endpoints

Generate Document

POST /documents/generate

Generate PDF compliance document from structured data.

Request Body:

{
  "tenant_id": "uuid",
  "document_type": "technical_documentation|conformity_declaration|instructions_for_use",
  "ai_system_id": "uuid"
}

Admin Endpoints

User Management

POST /admin/users
GET  /admin/users/{id}/status
PATCH /admin/subscriptions/{id}/limits

Finance & Analytics

GET /admin/finance/mrr
GET /admin/analytics/feature_usage
POST /admin/finance/invoices/generate

Exports

GET  /admin/exports/template/{type}
POST /admin/exports/generate

Key Management Endpoints

Key Status

GET /key-management/status

Rotate Key

POST /key-management/rotate

Crypto-Shredding

POST /key-management/shred

Irreversible tenant data deletion via encryption key destruction.

Error Responses

All endpoints return standard HTTP status codes with JSON error details:

{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

Common status codes:

  • 400: Bad Request — validation error
  • 401: Unauthorized — missing or invalid credentials
  • 403: Forbidden — insufficient permissions
  • 404: Not Found — resource doesn’t exist
  • 422: Unprocessable Entity — payload validation failed
  • 500: Internal Server Error