SigSentry Documentation

Creates a new analysis. Reads logs from your project's connected log sources within the given time window, runs a diagnosis, and returns the result.

Authentication

API key with analysis:create permission. Project-scoped or tenant-scoped (with X-Project-Id).

Endpoint

POST /v1/analyses

Request body

Field	Type	Required	Notes
`description`	`string` (1–5000 chars)	✓	What's wrong, in plain language
`timeStart`	`string` (ISO 8601)	✓	Window start; must be in the past
`timeEnd`	`string` (ISO 8601)	✓	Window end; must be after `timeStart` and not more than 60s in the future
`metadata`	`object<string,string>`	—	Free-form metadata attached to the analysis (e.g. ticket id, deploy id)

{
  "description": "Checkout 500s spiked after 14:00",
  "timeStart": "2026-04-25T14:00:00Z",
  "timeEnd": "2026-04-25T14:30:00Z",
  "metadata": {
    "ticketId": "ZD-12345"
  }
}

The analysis was created. If processing finished synchronously (small windows usually do) the status is complete and result is populated. Larger windows return processing and you should poll GET /v1/analyses/{id} for the result.

{
  "success": true,
  "data": {
    "id": "ana_x1y2z3...",
    "status": "complete",
    "description": "Checkout 500s spiked after 14:00",
    "timeStart": "2026-04-25T14:00:00Z",
    "timeEnd": "2026-04-25T14:30:00Z",
    "metadata": { "ticketId": "ZD-12345" },
    "createdAt": "2026-04-25T14:30:12Z",
    "result": {
      "summary": "Connection pool exhaustion in checkout-api...",
      "severity": "high",
      "confidence": 0.87,
      "rootCause": {
        "description": "...",
        "service": "checkout-api",
        "errorType": "ConnectionPoolExhausted",
        "category": "database"
      },
      "affectedServices": [
        { "serviceName": "checkout-api", "role": "origin", "errorCount": 234, "firstSeen": "...", "lastSeen": "..." }
      ],
      "timeline": [
        { "timestamp": "...", "service": "checkout-api", "level": "error", "message": "...", "isRootCause": true }
      ],
      "suggestedActions": [
        { "priority": 1, "action": "Increase the database connection pool ceiling", "rationale": "...", "type": "fix" }
      ],
      "logsScanned": 18437
    }
  }
}

Field	Type	Notes
`id`	`string`	The analysis id — use it to fetch, follow up, or rate
`status`	`'pending' \| 'processing' \| 'complete' \| 'partial' \| 'failed'`	Lifecycle status
`result`	`object \| null`	Present when `status` is `complete` or `partial`
`result.severity`	`'critical' \| 'high' \| 'medium' \| 'low' \| 'info'`
`result.confidence`	`number` (0–1)
`result.rootCause.category`	`string`	One of: `authentication`, `authorization`, `database`, `network`, `timeout`, `rate_limiting`, `validation`, `null_reference`, `configuration`, `dependency`, `memory`, `disk`, `unknown`
`result.affectedServices[].role`	`'origin' \| 'propagator' \| 'affected'`	Where this service sits in the failure chain
`result.suggestedActions[].type`	`'fix' \| 'investigate' \| 'mitigate' \| 'escalate'`

For deeper field-by-field guidance see Reading the result.

Error responses

Status	`error.code`	When
400	`VALIDATION_ERROR`	Description, time fields, or metadata failed validation
400	`INVALID_TIME_RANGE`	`timeEnd` is not after `timeStart`
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Key lacks `analysis:create`
403	`QUOTA_EXCEEDED`	Monthly quota reached, overage not enabled
500	`ANALYSIS_ERROR`	Server-side analysis failure

Example

curl -X POST https://api.sigsentry.com/v1/analyses \
  -H "Authorization: Bearer ss_secret_..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Checkout 500s spiked after 14:00",
    "timeStart": "2026-04-25T14:00:00Z",
    "timeEnd": "2026-04-25T14:30:00Z"
  }'

Idempotency

POST /v1/analyses honors the Idempotency-Key header — see Idempotency.

POST /v1/analyses

Authentication

Endpoint

Request body

Response

202 Accepted

Error responses

Example

Idempotency

On this page