API Reference

The OpsTrails HTTP API lets you record and query events programmatically. All endpoints use https://api.opstrails.dev as the base URL.

Authentication

All API requests require a Bearer token in the Authorization header. API keys are created in the console and come in two scopes:

READ_ONLY — Can query events. Cannot push events.
READ_WRITE — Can both push and query events.

📝 Note

API keys are prefixed with ot_ and stored as SHA-256 hashes. The full key is only shown once at creation time.

POST /api/v1/events

Record a new event on the timeline. Requires a READ_WRITE scoped API key.

Request Body

Field	Type	Required	Description
`specversion`	string	required	Must be "1.0".
`type`	string	required	Event type, e.g. "deployment", "rollback". Max 100 chars.
`source`	string	required	Event origin URI, e.g. "//github.com/org/repo". Max 500 chars.
`time`	string	required	Timestamp with timezone, or "NOW" for server time.
`id`	string	optional	Custom event ID. Auto-generated if omitted. Max 200 chars.
`subject`	string	optional	Free-form context label, e.g. "production". Max 50 chars.
`severity`	string	optional	One of LOW, MINOR, MAJOR, CRITICAL.
`version`	string	optional	Release version, e.g. "1.2.3". Max 50 chars.
`datacontenttype`	string	optional	MIME type of data field. Defaults to "application/json". Max 200 chars.
`dataschema`	string	optional	URI pointing to the schema for data. Max 500 chars.
`data`	object	optional	Arbitrary JSON. Supports "description" (max 1000 chars) and "timezone" (max 50 chars) plus any extra fields.

Time Format Rules

"NOW" (case-insensitive) — Uses the current server time
ISO 8601 with timezone — 2025-01-15T14:30:00Z or 2025-01-15T14:30:00+02:00
RFC 2822 — Wed, 15 Jan 2025 14:30:00 +0200
Bare datetimes without timezone are rejected
All timestamps are converted to UTC before storage

Minimal Example

bash

curl -X POST https://api.opstrails.dev/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "deployment",
    "source": "//github.com/myorg/myrepo",
    "time": "NOW"
  }'

Full Example

bash

curl -X POST https://api.opstrails.dev/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "deployment",
    "source": "//github.com/myorg/myrepo",
    "time": "2025-01-15T14:30:00Z",
    "subject": "production",
    "severity": "LOW",
    "version": "1.2.3",
    "datacontenttype": "application/json",
    "data": {
      "description": "Deployed to production",
      "timezone": "Europe/London"
    }
  }'

GET /api/v1/events

Query events from the timeline. Requires a READ_ONLY or READ_WRITE scoped API key.

Query Parameters

Field	Type	Required	Description
`type`	string	optional	Filter by event type, e.g. "deployment".
`source`	string	optional	Filter by event source, e.g. "//github.com/org/repo".
`subject`	string	optional	Filter by subject, e.g. "production".
`severity`	string	optional	Filter by severity: LOW, MINOR, MAJOR, or CRITICAL.
`from`	string	optional	Start of time range. ISO 8601 datetime.
`to`	string	optional	End of time range. ISO 8601 datetime.
`search`	string	optional	Free-text search across type, version, and source.
`limit`	number	optional	Max events to return (1-100, default 25).

Example

bash

curl "https://api.opstrails.dev/api/v1/events?type=deployment&subject=production&source=//github.com/myorg/myrepo" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /api/v1/metrics/webhook

Receives metrics data from connected analytics providers. Used internally by the analytics integration system. See Connecting Providers for setup instructions.

Error Responses

All errors return a JSON body with the following structure:

json

{
  "success": false,
  "error": "time: Timezone is required. Use ISO 8601 with offset (e.g. +02:00 or Z) or \"NOW\"",
  "code": "VALIDATION_ERROR"
}

Error Codes

Status	Code	Description
`401`	`UNAUTHORIZED`	Missing or invalid Authorization header, or API key not found
`403`	`FORBIDDEN`	API key has READ_ONLY scope — use a READ_WRITE key to push events
`400`	`VALIDATION_ERROR`	Missing or invalid fields, or time without timezone offset

Previous← Core Concepts NextCLI →