API Documentation — Opslytica

Getting Started

The Opslytica API is organized around REST. All requests and responses use JSON. Use your API key to authenticate, and you're ready to start ingesting events and querying metrics.

Base URL

https://api.opslytica.com/v1

All API requests are made to this base URL. HTTPS is required for all endpoints — plain HTTP requests will be rejected.

Key Concepts

Events are the raw data points you send to Opslytica — cycle times, milestone completions, SLA breaches, and more. Metrics are the aggregated, queryable views derived from those events. Capabilities represent business processes (e.g., Prior Authorization, Claims Processing) that group related metrics together.

Example Request

# Make your first API call
curl https://api.opslytica.com/v1/metrics \
  -H "X-Api-Key: your_api_key_here"

Response

{
  "data": [...],
  "meta": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 142
  }
}

Authentication

Authenticate your API requests by including your API key in the X-Api-Key header. You can manage your API keys from the Opslytica dashboard under Settings → API Keys.

Key Scopes

Each API key is assigned one of three scopes that control what operations it can perform:

Scope	Permissions
`Admin`	Full access: manage keys, organizations, and all read/write operations
`Query`	Read-only access to metrics, events, organizations, and capabilities
`Ingest`	Write-only access to submit events (single and batch)

Keep your API keys secure. Do not expose them in client-side code or public repositories. If a key is compromised, revoke it immediately and create a new one.

Authenticated Request

curl https://api.opslytica.com/v1/metrics \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json"

Unauthorized Response (401)

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

Forbidden Response (403)

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have the required scope."
  }
}

Ingest Event

POST /api/v1/events

Submit a single metric event. Events are the foundational data type in Opslytica — every metric, SLA check, and trend is derived from ingested events.

Request Body

Field	Type		Description
`orgCode`	string	Required	Organization code (e.g., `ACME`)
`capabilityCode`	string	Required	Capability code (e.g., `P2P`, `PA`, `CLAIMS`)
`metricType`	string	Required	Type of metric (e.g., `CycleTime`, `Milestone`, `Volume`)
`value`	number	Required	Numeric value of the event
`dimensions`	object	Optional	Key-value pairs for additional categorization
`timestamp`	string	Optional	ISO 8601 timestamp. Defaults to current time.
`correlationId`	string	Optional	Links related events (e.g., milestones of a single case)

Request

curl -X POST https://api.opslytica.com/v1/events \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "orgCode": "ACME",
    "capabilityCode": "P2P",
    "metricType": "CycleTime",
    "value": 14.5,
    "dimensions": {
      "urgency": "Standard",
      "region": "Northeast",
      "category": "Medical"
    },
    "correlationId": "CASE-2026-00482",
    "timestamp": "2026-03-18T10:30:00Z"
  }'

Response — 201 Created

{
  "id": "evt_8k3jF9xLm2nQ",
  "orgCode": "ACME",
  "capabilityCode": "P2P",
  "metricType": "CycleTime",
  "value": 14.5,
  "timestamp": "2026-03-18T10:30:00Z",
  "createdAt": "2026-03-18T10:30:01Z"
}

Batch Ingest

POST /api/v1/events/batch

Submit multiple events in a single request. This is the recommended approach for high-volume ingestion pipelines. The maximum batch size is 1,000 events per request.

Request Body

Field	Type		Description
`events`	array	Required	Array of event objects (same schema as single ingest)

Events are processed atomically — either all events in the batch succeed, or none are persisted. The response includes a count of accepted events and any validation errors.

Request

curl -X POST https://api.opslytica.com/v1/events/batch \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "orgCode": "ACME",
        "capabilityCode": "P2P",
        "metricType": "Milestone",
        "value": 1,
        "dimensions": { "milestone": "RequestReceived" },
        "correlationId": "CASE-2026-00482"
      },
      {
        "orgCode": "ACME",
        "capabilityCode": "P2P",
        "metricType": "Milestone",
        "value": 1,
        "dimensions": { "milestone": "ReviewComplete" },
        "correlationId": "CASE-2026-00482"
      }
    ]
  }'

Response — 201 Created

{
  "accepted": 2,
  "failed": 0,
  "errors": []
}

List Events

GET /api/v1/events

Retrieve a paginated list of ingested events. Supports filtering by organization, capability, metric type, and time range.

Query Parameters

Parameter	Type		Description
`orgCode`	string	Optional	Filter by organization
`capabilityCode`	string	Optional	Filter by capability
`metricType`	string	Optional	Filter by metric type
`from`	string	Optional	Start date (ISO 8601)
`to`	string	Optional	End date (ISO 8601)
`page`	integer	Optional	Page number (default: 1)
`pageSize`	integer	Optional	Results per page (default: 25, max: 100)

Request

curl https://api.opslytica.com/v1/events\
?orgCode=ACME&capabilityCode=P2P&from=2026-03-01 \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "data": [
    {
      "id": "evt_8k3jF9xLm2nQ",
      "orgCode": "ACME",
      "capabilityCode": "P2P",
      "metricType": "CycleTime",
      "value": 14.5,
      "timestamp": "2026-03-18T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 178
  }
}

Query Metrics

GET /api/v1/metrics

Query aggregated metrics across organizations and capabilities. Returns computed values like averages, percentiles, and SLA compliance rates derived from ingested events.

Query Parameters

Parameter	Type		Description
`orgCode`	string	Optional	Filter by organization code
`capability`	string	Optional	Filter by capability code
`from`	string	Optional	Start of date range (ISO 8601)
`to`	string	Optional	End of date range (ISO 8601)
`metricType`	string	Optional	Filter by metric type
`groupBy`	string	Optional	Group results by dimension (e.g., `urgency`, `region`)

Request

curl https://api.opslytica.com/v1/metrics\
?orgCode=ACME&capability=P2P&from=2026-03-01&to=2026-03-18 \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "data": [
    {
      "capabilityCode": "P2P",
      "metricType": "CycleTime",
      "count": 50,
      "avg": 18.4,
      "p50": 15.2,
      "p95": 42.7,
      "min": 2.1,
      "max": 68.3,
      "slaCompliance": 0.92
    }
  ],
  "meta": {
    "from": "2026-03-01T00:00:00Z",
    "to": "2026-03-18T23:59:59Z"
  }
}

Get Time Series

GET /api/v1/metrics/{id}/series

Retrieve time-series data for a specific metric. Useful for rendering charts and identifying trends over configurable time intervals.

Path Parameters

Parameter	Type		Description
`id`	string	Required	Metric identifier

Query Parameters

Parameter	Type		Description
`from`	string	Required	Start date (ISO 8601)
`to`	string	Required	End date (ISO 8601)
`interval`	string	Optional	`hour`, `day`, `week`, `month` (default: `day`)

Request

curl https://api.opslytica.com/v1/metrics/\
met_P2P_CycleTime/series\
?from=2026-03-01&to=2026-03-18&interval=day \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "metricId": "met_P2P_CycleTime",
  "interval": "day",
  "series": [
    { "date": "2026-03-01", "avg": 19.2, "count": 8 },
    { "date": "2026-03-02", "avg": 17.8, "count": 12 },
    { "date": "2026-03-03", "avg": 21.1, "count": 6 },
    { "date": "2026-03-04", "avg": 15.4, "count": 10 }
  ]
}

Get Metric Details

GET /api/v1/metrics/{id}

Retrieve detailed information about a specific metric, including its configuration, current value, SLA targets, and dimensional breakdowns.

Path Parameters

Parameter	Type		Description
`id`	string	Required	Metric identifier

Request

curl https://api.opslytica.com/v1/metrics/met_P2P_CycleTime \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "id": "met_P2P_CycleTime",
  "capabilityCode": "P2P",
  "metricType": "CycleTime",
  "displayName": "P2P Cycle Time",
  "unit": "hours",
  "slaTargets": {
    "Expedited": 8,
    "Urgent": 24,
    "Standard": 72
  },
  "current": {
    "avg": 18.4,
    "p95": 42.7,
    "compliance": 0.92
  }
}

List Organizations

GET /api/v1/organizations

Retrieve all organizations accessible to your API key. Each organization represents a tenant in the Opslytica multi-tenant architecture.

Results include the organization code, display name, status, and data retention settings.

Request

curl https://api.opslytica.com/v1/organizations \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "data": [
    {
      "id": "org_k8mXpL2n",
      "code": "ACME",
      "name": "ACME Behavioral Health",
      "status": "active",
      "dataRetentionDays": 365,
      "createdAt": "2025-06-15T00:00:00Z"
    },
    {
      "id": "org_j7nWqK9m",
      "code": "ANTHEM",
      "name": "Anthem Health Services",
      "status": "active",
      "dataRetentionDays": 730,
      "createdAt": "2025-08-01T00:00:00Z"
    }
  ]
}

Get Organization

GET /api/v1/organizations/{orgCode}

Retrieve details for a specific organization, including its configuration, active capabilities, and usage statistics.

Path Parameters

Parameter	Type		Description
`orgCode`	string	Required	Organization code

Request

curl https://api.opslytica.com/v1/organizations/ACME \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "id": "org_k8mXpL2n",
  "code": "ACME",
  "name": "ACME Behavioral Health",
  "status": "active",
  "dataRetentionDays": 365,
  "capabilities": ["P2P", "PA", "CLAIMS"],
  "usage": {
    "eventsThisMonth": 24831,
    "storageUsedMb": 142.6
  }
}

List Capabilities

GET /api/v1/capabilities

Retrieve all capabilities configured for an organization. Capabilities represent distinct business processes that Opslytica tracks — each with its own metrics, SLA targets, and dimensional breakdowns.

Query Parameters

Parameter	Type		Description
`orgCode`	string	Optional	Filter by organization

Request

curl https://api.opslytica.com/v1/capabilities\
?orgCode=ACME \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "data": [
    {
      "code": "P2P",
      "name": "Prior Authorization (P2P)",
      "metricTypes": ["CycleTime", "Milestone", "Volume"],
      "dimensions": ["urgency", "region", "category"],
      "eventCount": 12450
    },
    {
      "code": "CLAIMS",
      "name": "Claims Processing",
      "metricTypes": ["CycleTime", "Volume", "ErrorRate"],
      "dimensions": ["claimType", "payer"],
      "eventCount": 8920
    }
  ]
}

List API Keys

GET /api/v1/keys

Retrieve all API keys for your account. Only keys you have permission to view are returned. The key value is partially masked for security.

Requires Admin scope.

Request

curl https://api.opslytica.com/v1/keys \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "data": [
    {
      "id": "key_m3kL9xPq",
      "name": "Production Ingest",
      "scope": "Ingest",
      "prefix": "mk_live_a1b2...",
      "createdAt": "2026-01-10T14:00:00Z",
      "lastUsedAt": "2026-03-18T09:15:22Z"
    }
  ]
}

Create API Key

POST /api/v1/keys

Create a new API key. The full key value is only returned once in the response — store it securely, as it cannot be retrieved again.

Requires Admin scope.

Request Body

Field	Type		Description
`name`	string	Required	Human-readable name for the key
`scope`	string	Required	`Admin`, `Query`, or `Ingest`

Request

curl -X POST https://api.opslytica.com/v1/keys \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dashboard Read-Only",
    "scope": "Query"
  }'

Response — 201 Created

{
  "id": "key_p4nR7vWs",
  "name": "Dashboard Read-Only",
  "scope": "Query",
  "key": "mk_live_x9y8z7w6v5u4t3s2r1q0...",
  "createdAt": "2026-03-18T11:00:00Z"
}

Revoke API Key

DELETE /api/v1/keys/{keyId}

Permanently revoke an API key. This action is immediate and irreversible — any requests using the revoked key will receive a 401 Unauthorized response.

Requires Admin scope.

Path Parameters

Parameter	Type		Description
`keyId`	string	Required	The key identifier to revoke

Request

curl -X DELETE https://api.opslytica.com/v1/keys/key_m3kL9xPq \
  -H "X-Api-Key: mk_live_a1b2c3d4e5f6..."

Response — 200 OK

{
  "id": "key_m3kL9xPq",
  "status": "revoked",
  "revokedAt": "2026-03-18T11:05:00Z"
}

Errors

Opslytica uses conventional HTTP status codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, 4xx indicate a client error, and 5xx indicate a server error.

HTTP Status Codes

200	OK — Request succeeded
201	Created — Resource successfully created
400	Bad Request — Invalid parameters or malformed request body
401	Unauthorized — Missing or invalid API key
403	Forbidden — API key lacks the required scope
404	Not Found — The requested resource does not exist
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Something went wrong on our end

Error Response Format

{
  "error": {
    "code": "bad_request",
    "message": "The 'orgCode' field is required.",
    "details": [
      {
        "field": "orgCode",
        "issue": "must not be empty"
      }
    ]
  }
}

Validation Error (400)

{
  "error": {
    "code": "validation_error",
    "message": "Request body contains invalid fields.",
    "details": [
      {
        "field": "value",
        "issue": "must be a positive number"
      },
      {
        "field": "capabilityCode",
        "issue": "unknown capability 'INVALID'"
      }
    ]
  }
}

Rate Limits

API requests are rate-limited per API key to ensure fair usage and platform stability. Limits vary by endpoint category:

Category	Limit
Ingest (POST /events, /events/batch)	5,000 requests/minute
Query (GET /metrics, /events, /organizations, etc.)	1,000 requests/minute
Admin (POST/DELETE /keys)	100 requests/minute

Rate Limit Headers

Every response includes headers that report your current rate limit status:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When you exceed the limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your client to handle rate limiting gracefully.

Rate Limit Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset: 1742310000
Content-Type: application/json

429 Response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 12 seconds.",
    "retryAfter": 12
  }
}