API Reference

The TeamSentry REST API lets you programmatically access security data, manage incidents, and integrate with AI agents. Every response includes a machine-readable summary field optimized for LLM consumption.

Authentication

All API requests require a valid API key sent as a Bearer token in the Authorization header. API keys are scoped to an organization and can be created from the TeamSentry dashboard under Settings > Agent API.

Creating an API Key

• Navigate to Settings > Agent API in your dashboard
• Click Create API Key
• Give it a descriptive name (e.g., "Claude Desktop", "Security Bot")
• Copy the key immediately -- it will not be shown again

API keys follow the format tsk_live_xxxxxxxxxxxx for production keys and tsk_test_xxxxxxxxxxxx for test keys.

Using Your API Key

Authorization: Bearer tsk_live_your_api_key_here

curl https://api.teamsentry.ai/v1/overview \
  -H "Authorization: Bearer tsk_live_your_api_key_here" \
  -H "Content-Type: application/json"

Base URL

All API endpoints are relative to:

https://api.teamsentry.ai/v1

Response Format

All responses are JSON. Every successful response includes a top-level summary field containing a natural-language description of the data, optimized for AI agent consumption.

{
  "summary": "Human-readable summary of the response data.",
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Overview

{
  "summary": "142 monitored users. 3 high-risk users. 2 open incidents.",
  "organization": {
    "total_users": 142,
    "monitored_users": 142
  },
  "risk_distribution": {
    "critical": 1,
    "high": 2,
    "medium": 8,
    "low": 47,
    "minimal": 84
  },
  "open_incidents": 2
}

Users

{
  "summary": "[email protected] has HIGH risk (82). 4 active rules.",
  "user": {
    "email": "[email protected]",
    "name": "John Smith",
    "risk_score": 82,
    "risk_level": "high"
  },
  "active_rules": [
    {
      "rule_id": "impossible_travel",
      "severity": "high",
      "mitre_tactic": "TA0001",
      "triggered_at": "2025-01-15T08:22:00Z"
    }
  ]
}

Incidents

AI Usage

Apps

Agent-Specific

These endpoints are specifically designed for AI agent consumption with enriched summaries and structured context.

Error Codes

The API uses standard HTTP status codes. Error responses include a structured JSON body with error details.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or expired.",
    "status": 401
  },
  "request_id": "req_abc123"
}

Rate Limits

API requests are rate limited to ensure fair usage and platform stability.

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1705312800

When rate limited, the API returns a 429 status with a Retry-After header indicating the number of seconds to wait before retrying.

Webhooks

Webhooks deliver real-time event notifications to your endpoint via HTTP POST. Configure webhook endpoints in your dashboard under Settings > Webhooks.

Event Format

All webhook payloads follow a standard envelope format:

{
  "id": "evt_abc123",
  "event": "incident.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "incident_id": "inc_8f3k2j",
    "severity": "high",
    "title": "Possible account takeover detected",
    "affected_user": "[email protected]"
  }
}

HMAC Verification

Every webhook request includes an X-TeamSentry-Signature header containing an HMAC-SHA256 signature of the raw request body, using your webhook secret as the key.

import hmac
import hashlib

def verify_signature(payload_body, signature, secret):
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(
        f"sha256={expected}",
        signature
    )

Retry Policy

If your endpoint does not respond with a 2xx status within 10 seconds, TeamSentry retries delivery with exponential backoff:

• Retry 1: after 30 seconds
• Retry 2: after 2 minutes
• Retry 3: after 10 minutes
• Retry 4: after 1 hour
• Retry 5: after 6 hours (final attempt)

After 5 failed retries, the event is marked as failed and logged in your dashboard. You can manually replay failed events from the webhook settings page.