API Overview

The Noxys API is a REST-based service for programmatic access to your AI interaction data, policies, and security events. Use it to build integrations, custom tools, and automate workflows.

API Basics

Base URL: https://api.noxys.cloud/api/v1/ (for SaaS)

For self-hosted deployments, use your instance URL: https://your-domain.com/api/v1/

Protocol: HTTPS (TLS 1.2+) required for all requests

Response Format: JSON

Authentication: JWT Bearer token (see Authentication)

Quick Example

# Get a token
TOKEN=$(curl -X POST https://api.noxys.cloud/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@acme.fr","password":"your-password"}' \
  | jq -r '.token')

# Use the token
curl https://api.noxys.cloud/api/v1/interactions \
  -H "Authorization: Bearer $TOKEN"

Core Concepts

AIInteraction

The canonical data model in Noxys. Every AI interaction (prompt to ChatGPT, message to Claude, etc.) is normalized into a single schema containing:

• Platform ID: Which AI service (chatgpt, claude, gemini, etc.)
• Content Hash: SHA-256 hash of the interaction content (raw text never stored)
• Classifications: Detected PII (email, phone, NIR, credit card, etc.)
• Risk Score: Numerical risk assessment (0-1)
• Policy Decisions: Actions taken (Block, Coach, Log)
• Metadata: URL, model, user, timestamp, etc.

Policies

Rules that enforce data protection. Learn more in the Policies API.

Policy actions:

• Block: Prevent interaction from reaching AI service
• Coach: Warn user (non-blocking, yellow banner)
• Log: Record silently (no user notification)

Classification Tiers

Tier	Where	Speed	Coverage
Tier 1	Browser extension	<10ms	Email, phone, IBAN, credit cards, NIR, SIRET (regex-based)
Tier 2	Backend	~30ms	Names, medical terms, legal refs, IP addresses, API keys (Presidio + custom models)
Tier 3	Async	~500ms	Deep semantic classification using small language models

Endpoints Summary

Endpoint	Method	Purpose	Auth Required
/auth/login	POST	Get JWT token	No
/interactions	POST/GET	Create or list AI interactions	Yes
/interactions/:id	GET	Get interaction details	Yes
/interactions/batch	POST	Batch create interactions	Yes
/policies	GET/POST	List or create policies	Yes
/policies/:id	GET/PUT/DELETE	Manage single policy	Yes
/inventory	GET	List AI services in use	Yes
/alerts	GET	List security alerts	Yes
/audit-log	GET	Admin activity log	Yes (Admin)
/dashboard/stats	GET	Aggregated statistics	Yes
/classification/classify	POST	Classify text (Tier 2)	Yes (Admin)
/healthz	GET	Liveness probe	No
/readyz	GET	Readiness probe	No
/metrics	GET	Prometheus metrics	No
/ws	WS	WebSocket for real-time updates	Yes

Rate Limiting

API calls are rate-limited to protect service stability:

Endpoint	Limit	Window
/auth/login	5 requests/minute	Per IP address
All other endpoints	1,000 requests/minute	Per tenant

When you exceed the limit, the API returns HTTP 429 Too Many Requests. See Rate Limiting for details on headers and retry behavior.

Error Handling

All errors return a consistent JSON format:

{
  "error": "Human-readable error message"
}

Common HTTP Status Codes:

Code	Meaning	Example
200	Success	Request succeeded
201	Created	New resource created (POST)
204	No Content	Delete succeeded (no response body)
400	Bad Request	Missing field, invalid format
401	Unauthorized	Missing or expired token
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate name or constraint violation
429	Rate Limited	Too many requests
500	Server Error	Unexpected error (contact support)

Pagination

List endpoints support pagination:

curl "https://api.noxys.cloud/api/v1/interactions?page=2&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters:

• page — Page number (1-based, default: 1)
• limit — Items per page (default: 50, max: 500)

Response Headers:

• X-Total-Count — Total records matching the query
• X-Page — Current page number
• X-Per-Page — Items returned on this page
• X-Total-Pages — Total pages available

Supported Languages & SDKs

Full code examples are provided for:

• Python: requests library
• JavaScript/TypeScript: Fetch API, async/await
• Go: net/http standard library
• cURL: For quick manual testing

OpenAPI Specification

The complete OpenAPI 3.1 specification is available at:

• Swagger UI: https://api.noxys.cloud/api/docs
• OpenAPI JSON: https://api.noxys.cloud/api/docs/openapi.json
• OpenAPI YAML: https://api.noxys.cloud/api/docs/openapi.yaml

Download and use with tools like:

• Postman
• Insomnia
• OpenAPI code generators

What's Next?

• Authentication — Get tokens and manage auth
• Events (Interactions) — Create and query AI interactions
• Policies — Manage data loss prevention rules
• Users — User management endpoints
• Webhooks — Real-time event delivery

Need Help?

• Email: support@noxys.eu (feature questions, setup issues)
• Security: security@noxys.eu (security vulnerabilities)
• Docs: This API reference
• Status: status.noxys.cloud