Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.causeflow.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Error responses

When a request fails, the API returns a JSON error object with a machine-readable error code and a human-readable message: 
{
  "error": "incident_not_found",
  "message": "No incident was found with the provided ID."
}

​
HTTP status codes

StatusCodeMeaning
400Bad RequestThe request body or query parameters are invalid or missing required fields
401UnauthorizedNo valid authentication token was provided
403ForbiddenThe authenticated user does not have permission for this operation
404Not FoundThe requested resource does not exist
409ConflictA duplicate resource already exists (e.g. duplicate incident title within the same window)
429Too Many RequestsRate limit exceeded — see X-RateLimit-Reset for when to retry
500Internal Server ErrorAn unexpected error occurred on the CauseFlow side
503Service UnavailableThe service is temporarily unavailable — retry with exponential backoff

​
Example error responses

{
  "error": "validation_error",
  "message": "Field 'description' is required and must be between 10 and 4000 characters."
}

​
Pagination

List endpoints use cursor-based pagination. This approach is stable under concurrent writes — pages do not shift when new records are inserted.

​
Request parameters

ParameterTypeDefaultMaximumDescription
limitinteger20100Number of items to return per page
cursorstring——Opaque cursor token from the previous response

​
Response structure

{
  "items": [
    { "incidentId": "inc_01HX9VTPQR3KF8MZWBYD5N6JCE", "title": "Database latency spike", "..." : "..." },
    { "incidentId": "inc_01HX9VTPQR3KF8MZWBYD5N6JCF", "title": "API gateway 5xx surge", "...": "..." }
  ],
  "cursor": "eyJpZCI6Imlu...",
  "count": 47
}
FieldTypeDescription
itemsarrayThe page of results
cursorstringPass this value as cursor in the next request to fetch the next page. null when there are no more pages.
countintegerTotal number of matching records across all pages

​
Paginating through all results

# First page
curl "https://api.causeflow.ai/v1/incidents?limit=20" \
  -H "Authorization: Bearer <token>"

# Next page — pass the cursor from the previous response
curl "https://api.causeflow.ai/v1/incidents?limit=20&cursor=eyJpZCI6Imlu..." \
  -H "Authorization: Bearer <token>"
Cursor tokens are opaque and time-limited. Do not store cursors for longer than a single pagination session.