API Reference

Welcome to the Tamandua Sentinel EDR API Reference. This documentation provides comprehensive coverage of all REST API endpoints available for integrating with the Tamandua platform.

Base URL

All API requests should be made to:

https://api.tamandua.io/api/v1

For self-hosted deployments, replace with your server address:

https://your-server.example.com/api/v1

Authentication

The Tamandua API supports multiple authentication methods:

API Key Prefixes:

• tam_live_ - Production API keys
• tam_dev_ - Development API keys
• tam_test_ - Test environment keys

See Authentication for detailed setup instructions.

Request Format

Headers

All requests must include:

Content-Type: application/json
Authorization: Bearer <your_api_key>

For session-authenticated requests from the web dashboard, include the CSRF token:

X-CSRF-Token: <csrf_token>

Request Body

Request bodies should be JSON-encoded:

{
  "field": "value",
  "nested": {
    "key": "value"
  }
}

Response Format

Success Response

All successful responses follow this structure:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 1234,
    "total_pages": 25
  }
}

For single-resource responses:

{
  "data": {
    "id": "uuid",
    "field": "value"
  }
}

Error Response

Error responses include an error message and optional details:

{
  "error": "Error message",
  "details": {
    "field": ["validation error"]
  }
}

Rate Limits

API requests are rate-limited to protect system stability:

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1620000000

When rate limited, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Pagination

List endpoints support pagination with the following parameters:

Example request:

curl -X GET "https://api.tamandua.io/api/v1/alerts?page=2&per_page=25" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example response with pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}

Sorting

List endpoints support sorting:

Example:

curl -X GET "https://api.tamandua.io/api/v1/alerts?sort_by=severity&sort_order=desc" \
  -H "Authorization: Bearer tam_live_xxxxx"

Filtering

Most list endpoints support filtering via query parameters:

# Filter alerts by severity and status
curl -X GET "https://api.tamandua.io/api/v1/alerts?severity=critical&status=open" \
  -H "Authorization: Bearer tam_live_xxxxx"

For complex filtering, use the search endpoints with POST:

curl -X POST "https://api.tamandua.io/api/v1/alerts/search" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "severity": ["critical", "high"],
    "status": "open",
    "date_from": "2024-01-01T00:00:00Z",
    "mitre_techniques": ["T1059"]
  }'

Error Codes

HTTP Status Codes

Error Types

Common error types returned in the error field:

API Versioning

The current API version is v1. The version is included in the URL path:

/api/v1/agents
/api/v1/alerts

We maintain backward compatibility within major versions. Breaking changes will be introduced in new major versions (e.g., /api/v2/).

Timestamps

All timestamps are returned in ISO 8601 format with UTC timezone:

2024-01-15T14:30:00Z

When sending timestamps, use the same format or Unix timestamps:

{
  "date_from": "2024-01-01T00:00:00Z",
  "date_to": "2024-01-31T23:59:59Z"
}

Available Endpoints

Core Resources

Additional APIs

• Rules API - YARA and Sigma rule management
• IOC API - Indicator of Compromise management
• Threat Intelligence - Feed integration and enrichment
• MITRE ATT&CK - Coverage and heatmap data
• Investigations - Case management
• Playbooks - Automated response workflows

SDK and Client Libraries

Official SDKs are available for:

• Python: pip install tamandua-sdk
• JavaScript/TypeScript: npm install @tamandua/sdk
• Go: go get github.com/tamandua-edr/go-sdk

Support

• Documentation: https://docs.tamandua.io
• API Status: https://status.tamandua.io
• Support Email: support@tamandua.io
• GitHub Issues: https://github.com/treant-lab/tamandua-community/issues