Timeline API Reference
| Field | Value |
|---|---|
| Source spec | timeline/openapi/v1.json |
| OpenAPI version | 3.1.1 |
| API version | 1.0.0 |
| Operations | 41 |
| Path filter | All paths |
Operations
DELETE /api/v1/audit/actors/{actorId}/pii
GDPR right-to-erasure. Redacts actor_email, actor_ip, actor_user_agent (and actor_name for personal/sensitive rows) for every unified audit event owned by this actor in the current tenant. Returns the count of redacted rows. The hash chain remains intact.
| Property | Value |
|---|---|
| Operation ID | RedactAuditActorPii |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
actorId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/anomalies
Get anomaly alerts from unified audit events.
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditAnomalies |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
acknowledged | query | no | |
limit | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/anomalies/_pending-dispatch
Get pending, unacknowledged anomaly alerts for Notify dispatch fan-out.
| Property | Value |
|---|---|
| Operation ID | GetPendingUnifiedAuditAnomalyDispatch |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
limit | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/anomalies/rules
List tenant-scoped anomaly rule configuration.
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditAnomalyRules |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
POST /api/v1/audit/anomalies/rules
Create tenant-scoped anomaly rule configuration.
| Property | Value |
|---|---|
| Operation ID | CreateUnifiedAuditAnomalyRule |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | application/json |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
PUT /api/v1/audit/anomalies/rules/{id}
Update tenant-scoped anomaly rule configuration.
| Property | Value |
|---|---|
| Operation ID | UpdateUnifiedAuditAnomalyRule |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | application/json |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
DELETE /api/v1/audit/anomalies/rules/{id}
Delete tenant-scoped anomaly rule configuration.
| Property | Value |
|---|---|
| Operation ID | DeleteUnifiedAuditAnomalyRule |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
POST /api/v1/audit/anomalies/{alertId}/acknowledge
Acknowledge an anomaly alert.
| Property | Value |
|---|---|
| Operation ID | AcknowledgeUnifiedAuditAnomaly |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
alertId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
POST /api/v1/audit/anomalies/{alertId}/dispatch-failed
Mark a pending anomaly alert as failed after Notify dispatcher exhausts retries.
| Property | Value |
|---|---|
| Operation ID | MarkUnifiedAuditAnomalyDispatchFailed |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
alertId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
POST /api/v1/audit/anomalies/{alertId}/dispatched
Mark a pending anomaly alert dispatched after Notify fan-out succeeds.
| Property | Value |
|---|---|
| Operation ID | MarkUnifiedAuditAnomalyDispatched |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
alertId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/chain/verify
Verify the hash chain integrity for a tenant’s audit events.
| Property | Value |
|---|---|
| Operation ID | VerifyUnifiedAuditChain |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
fromSequence | query | no | |
tenantId | query | no | |
toSequence | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/correlations
Get unified audit correlation clusters.
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditCorrelations |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
endDate | query | no | |
limit | query | no | |
startDate | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/correlations/{correlationId}
Get a unified audit correlation cluster by correlation ID.
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditCorrelationById |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
correlationId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/events
Get unified audit events with filtering and cursor pagination. Each event carries actor (whom the event is about) and ingestIdentity (the verified caller that appended it: subject, clientId, producer); ingestIdentity is null for events written before Timeline recorded the writer.
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditEvents |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
Actions | query | no | |
ActorEmail | query | no | |
ActorId | query | no | |
ActorIp | query | no | |
ActorName | query | no | |
CorrelationId | query | no | |
Cursor | query | no | |
EndDate | query | no | |
Limit | query | no | |
Modules | query | no | |
ResourceId | query | no | |
ResourceName | query | no | |
ResourceType | query | no | |
Search | query | no | |
Severities | query | no | |
StartDate | query | no | |
Tags | query | no | |
TenantId | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
GET /api/v1/audit/events/{eventId}
Get a single unified audit event by ID, including its ingestIdentity (the verified caller that appended it; null for events written before Timeline recorded the writer).
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditEventById |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
eventId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
404 | Not Found | - |
POST /api/v1/audit/export
Request a unified audit export.
| Property | Value |
|---|---|
| Operation ID | RequestUnifiedAuditExport |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | application/json |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/export/{exportId}
Get unified audit export status.
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditExportStatus |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
exportId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
POST /api/v1/audit/ingest
Ingest a single audit event from a service. Requires an authenticated caller carrying audit:ingest (or timeline:write). An audit:ingest producer writes the event to the tenantId it names in the body; an event without a tenantId is a platform-level event and joins the reserved installation tenant’s own hash chain, which only global administrators can read. A timeline:write caller without audit:ingest always writes to its own authenticated tenant: a different body tenantId returns 403 tenant_claim_mismatch, a caller whose tenant is the reserved installation tenant gets 403 tenant_reserved, and a caller without a tenant gets 400 tenant_missing. Nothing is written to a default tenant. Every stored event records the verified caller that appended it (ingestIdentity: subject, clientId, producer), returned on reads. An audit:ingest producer may record an actor other than itself (it files events on behalf of the user its service served); any other caller records only itself: actor.id must be its verified subject (filled from the credential when omitted), and a supplied actor name or e-mail must match its verified claims, otherwise 403 actor_claim_mismatch. A caller without a verifiable subject or client id gets 403 audit_ingest_identity_missing. Returns 202 Accepted.
| Property | Value |
|---|---|
| Operation ID | IngestUnifiedAuditEvent |
| Tags | Unified Audit Ingest |
| Auth | Not declared |
| Request body | application/json |
Responses:
| Status | Description | Content types |
|---|---|---|
202 | Accepted | - |
400 | Bad Request | - |
401 | Unauthorized | - |
403 | Forbidden | - |
503 | Service Unavailable | - |
GET /api/v1/audit/retention-policies
Returns the effective retention window in days per classification (none, personal, sensitive, restricted) for the caller’s tenant, with the platform-default fallback applied.
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditRetentionPolicies |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/stats
Get unified audit statistics summary.
| Property | Value |
|---|---|
| Operation ID | GetUnifiedAuditStats |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
endDate | query | no | |
startDate | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/audit/timeline/search
Search unified audit timeline entries.
| Property | Value |
|---|---|
| Operation ID | SearchUnifiedAuditTimeline |
| Tags | Unified Audit |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
endDate | query | no | |
limit | query | no | |
q | query | no | |
startDate | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/buildinfo
API alias for /buildinfo.json (same payload).
| Property | Value |
|---|---|
| Operation ID | StellaOpsBuildInfoApi |
| Tags | StellaOps.Timeline.WebService |
| Auth | Not declared |
| Request body | - |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /api/v1/timeline
List timeline events
Returns timeline events filtered by tenant and optional query parameters.
| Property | Value |
|---|---|
| Operation ID | timeline_api_v1_query |
| Tags | timeline-indexer |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
after | query | no | |
correlationId | query | no | |
eventType | query | no | |
limit | query | no | |
severity | query | no | |
since | query | no | |
source | query | no | |
traceId | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
400 | Bad Request | application/problem+json |
401 | Unauthorized | - |
POST /api/v1/timeline/events
Ingest timeline event
Ingests one timeline event envelope into the caller’s authenticated tenant through the validated indexer store: 202 when stored, 200 for a duplicate event id. A caller without a resolved tenant gets 400 tenant_missing, an invalid envelope 400, and an envelope that names another tenant 403; nothing is written in those cases.
| Property | Value |
|---|---|
| Operation ID | timeline_api_v1_ingest_event |
| Tags | timeline-indexer |
| Auth | Not declared |
| Request body | application/json |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
202 | Accepted | application/json |
400 | Bad Request | application/problem+json |
401 | Unauthorized | - |
403 | Forbidden | application/problem+json |
GET /api/v1/timeline/hlc/export/{exportId}
Get the status of an export operation
| Property | Value |
|---|---|
| Operation ID | GetExportStatus |
| Tags | Export |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
exportId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
404 | Not Found | - |
GET /api/v1/timeline/hlc/export/{exportId}/download
Download the completed export bundle
| Property | Value |
|---|---|
| Operation ID | DownloadExport |
| Tags | Export |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
exportId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
404 | Not Found | - |
GET /api/v1/timeline/hlc/replay/{replayId}
Get the status of a replay operation
| Property | Value |
|---|---|
| Operation ID | GetReplayStatus |
| Tags | Replay |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
replayId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
404 | Not Found | - |
DELETE /api/v1/timeline/hlc/replay/{replayId}
Delete/cancel a replay operation
| Property | Value |
|---|---|
| Operation ID | DeleteReplay |
| Tags | Replay |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
replayId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
404 | Not Found | - |
POST /api/v1/timeline/hlc/replay/{replayId}/cancel
Cancel an in-progress replay operation
| Property | Value |
|---|---|
| Operation ID | CancelReplay |
| Tags | Replay |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
replayId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
404 | Not Found | - |
GET /api/v1/timeline/hlc/{correlationId}
Get events for a correlation ID, ordered by HLC timestamp
| Property | Value |
|---|---|
| Operation ID | GetTimeline |
| Tags | Timeline HLC |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
correlationId | path | yes | |
fromHlc | query | no | |
kinds | query | no | |
limit | query | no | |
offset | query | no | |
services | query | no | |
toHlc | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
400 | Bad Request | application/json |
404 | Not Found | - |
GET /api/v1/timeline/hlc/{correlationId}/critical-path
Get the critical path (longest latency stages) for a correlation
| Property | Value |
|---|---|
| Operation ID | GetCriticalPath |
| Tags | Timeline HLC |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
correlationId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
404 | Not Found | - |
POST /api/v1/timeline/hlc/{correlationId}/export
Export timeline events as NDJSON bundle with optional DSSE signing
| Property | Value |
|---|---|
| Operation ID | ExportTimeline |
| Tags | Export |
| Auth | Not declared |
| Request body | application/json |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
correlationId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
202 | Accepted | application/json |
400 | Bad Request | application/json |
POST /api/v1/timeline/hlc/{correlationId}/replay
Initiate deterministic replay for a correlation ID
| Property | Value |
|---|---|
| Operation ID | InitiateReplay |
| Tags | Replay |
| Auth | Not declared |
| Request body | application/json |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
correlationId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
202 | Accepted | application/json |
400 | Bad Request | application/json |
GET /api/v1/timeline/{eventId}
Get timeline event
Returns a single timeline event by event identifier for the current tenant.
| Property | Value |
|---|---|
| Operation ID | timeline_api_v1_get_by_id |
| Tags | timeline-indexer |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
eventId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
400 | Bad Request | application/problem+json |
401 | Unauthorized | - |
404 | Not Found | - |
GET /api/v1/timeline/{eventId}/evidence
Get event evidence
Returns evidence linkage for a timeline event, including bundle and attestation references.
| Property | Value |
|---|---|
| Operation ID | timeline_api_v1_get_evidence |
| Tags | timeline-indexer |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
eventId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
400 | Bad Request | application/problem+json |
401 | Unauthorized | - |
404 | Not Found | - |
GET /buildinfo.json
Image build provenance (module, gitSha, gitCommitTime, imageBuiltAt, branch) for drift detection.
| Property | Value |
|---|---|
| Operation ID | StellaOpsBuildInfoFile |
| Tags | StellaOps.Timeline.WebService |
| Auth | Not declared |
| Request body | - |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /doctor/timeline/checks
| Property | Value |
|---|---|
| Operation ID | - |
| Tags | Health |
| Auth | Not declared |
| Request body | - |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | - |
GET /timeline
List timeline events
Returns timeline events filtered by tenant and optional query parameters.
| Property | Value |
|---|---|
| Operation ID | timeline_query |
| Tags | timeline-indexer |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
after | query | no | |
correlationId | query | no | |
eventType | query | no | |
limit | query | no | |
severity | query | no | |
since | query | no | |
source | query | no | |
traceId | query | no |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
400 | Bad Request | application/problem+json |
401 | Unauthorized | - |
POST /timeline/events
Ingest timeline event
Ingests one timeline event envelope into the caller’s authenticated tenant through the validated indexer store: 202 when stored, 200 for a duplicate event id. A caller without a resolved tenant gets 400 tenant_missing, an invalid envelope 400, and an envelope that names another tenant 403; nothing is written in those cases.
| Property | Value |
|---|---|
| Operation ID | timeline_ingest_event |
| Tags | timeline-indexer |
| Auth | Not declared |
| Request body | application/json |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
202 | Accepted | application/json |
400 | Bad Request | application/problem+json |
401 | Unauthorized | - |
403 | Forbidden | application/problem+json |
GET /timeline/{eventId}
Get timeline event
Returns a single timeline event by event identifier for the current tenant.
| Property | Value |
|---|---|
| Operation ID | timeline_get_by_id |
| Tags | timeline-indexer |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
eventId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
400 | Bad Request | application/problem+json |
401 | Unauthorized | - |
404 | Not Found | - |
GET /timeline/{eventId}/evidence
Get event evidence
Returns evidence linkage for a timeline event, including bundle and attestation references.
| Property | Value |
|---|---|
| Operation ID | timeline_get_evidence |
| Tags | timeline-indexer |
| Auth | Not declared |
| Request body | - |
Parameters:
| Name | In | Required | Description |
|---|---|---|---|
eventId | path | yes |
Responses:
| Status | Description | Content types |
|---|---|---|
200 | OK | application/json |
400 | Bad Request | application/problem+json |
401 | Unauthorized | - |
404 | Not Found | - |