API Reference

Complete REST API documentation for TalonAI. All endpoints require authentication via API key.

Authentication

All API requests require an API key in the Authorization header:

1curl https://api.talonai.io/v1/analyze \
2  -H "Authorization: Bearer sk_live_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{"content": "Hello, world!"}'

Keep Your API Key Secure

Never expose your API key in client-side code or public repositories. Use environment variables and server-side requests.

Base URL

All API endpoints are relative to:

1https://api.talonai.io/v1

Endpoints

POST /analyze

Analyze content for security threats. Returns detailed analysis including risk score, detected threats, and recommended action.

Request Body

1{
2  "content": "string (required)",
3  "options": {
4    "categories": ["PROMPT_INJECTION", "PII_EXPOSURE"],
5    "riskThreshold": 70,
6    "detailed": true,
7    "context": {
8      "userId": "string",
9      "sessionId": "string"
10    }
11  }
12}

Response

1{
2  "allowed": true,
3  "action": "ALLOW",
4  "riskScore": 15,
5  "threats": [
6    {
7      "category": "ANOMALY",
8      "severity": "LOW",
9      "confidence": 0.45,
10      "description": "Unusual request pattern detected",
11      "evidence": ["unusual greeting pattern"]
12    }
13  ],
14  "processingTimeMs": 45,
15  "requestId": "req_abc123"
16}

POST /protect

Analyze and sanitize content. Returns the original analysis plus sanitized content with sensitive data redacted.

Request Body

1{
2  "content": "My SSN is 123-45-6789",
3  "options": {
4    "redactPII": true,
5    "redactCredentials": true
6  }
7}

Response

1{
2  "allowed": true,
3  "sanitizedContent": "My SSN is [SSN_REDACTED]",
4  "analysis": {
5    "riskScore": 65,
6    "threats": [
7      {
8        "category": "PII_EXPOSURE",
9        "severity": "HIGH",
10        "confidence": 0.98,
11        "description": "Social Security Number detected"
12      }
13    ]
14  },
15  "redactions": [
16    {
17      "type": "SSN",
18      "original": "123-45-6789",
19      "replacement": "[SSN_REDACTED]",
20      "position": { "start": 11, "end": 22 }
21    }
22  ]
23}

GET /policies

List all security policies for your organization.

Response

1{
2  "policies": [
3    {
4      "id": "pol_abc123",
5      "name": "Default Policy",
6      "description": "Default security policy",
7      "enabled": true,
8      "rules": [...],
9      "createdAt": "2024-01-01T00:00:00Z",
10      "updatedAt": "2024-01-15T12:00:00Z"
11    }
12  ],
13  "total": 1
14}

POST /policies

Create a new security policy.

Request Body

1{
2  "name": "Strict Policy",
3  "description": "High-security policy for production",
4  "enabled": true,
5  "rules": [
6    {
7      "condition": {
8        "field": "risk_score",
9        "operator": "greater_than",
10        "value": 50
11      },
12      "action": "BLOCK"
13    }
14  ]
15}

Error Responses

All errors follow a consistent format:

1{
2  "error": {
3    "code": "AUTHENTICATION_FAILED",
4    "message": "Invalid API key provided",
5    "requestId": "req_xyz789"
6  }
7}

Error Codes

Code	HTTP Status	Description
AUTHENTICATION_FAILED	401	Invalid or missing API key
RATE_LIMIT_EXCEEDED	429	Too many requests
VALIDATION_ERROR	400	Invalid request body
INTERNAL_ERROR	500	Server error

Rate Limits

API rate limits depend on your plan:

Plan	Requests/minute	Requests/day
Free	60	1,000
Pro	600	100,000
Enterprise	Unlimited	Unlimited

Rate limit headers are included in all responses:

1X-RateLimit-Limit: 60
2X-RateLimit-Remaining: 45
3X-RateLimit-Reset: 1704067200

Webhooks

Configure webhooks to receive real-time notifications for security events. See the Webhooks documentation for details.

SDKs

We provide official SDKs for common languages. See the SDK documentation for language-specific guides: