Authenticated public v1 API
API reference.
Explore request schemas and response contracts. Create a scoped key in the portal and send requests from your server.
Base URL: https://api.jylus.ai/api
Authentication: Authorization: Bearer YOUR_API_KEY. The key determines tenant and production/test scope. A namespace filters data inside that scope.
Limits: read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Query operations also expose concurrency headers after acquiring a lease. For 429, respect Retry-After.
Idempotency: writes require an 8–128 character Idempotency-Key. Completed keys replay their original receipt for 24 hours within the same workspace/environment. Reuse a key for the same logical write; changing a payload does not create a new write under that key. Poll the receipt until verified.
Versioning: /v1 identifies the request contract. Context Packs also carry schema_version. Tolerate additive response fields and review a documented version change before migrating contracts.
History: query/analyze history requires where.timestamp.gte or gt within your plan's retention. Check both scan completeness and Context Pack proof completeness.
POST /v1/eventsIngest one or more events
Idempotency keys are workspace- and production/test-scoped. A completed key replays its original 202 receipt for 24 hours; use the same key only for retries of the same logical write. The key is not a payload comparison mechanism. An in-flight key returns 409; wait for Retry-After. Receipt acceptance is distinct from verified searchability.
Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
}
}
]Request example
{
"stream": "demo",
"namespace": "my-demo",
"events": [
{
"id": "record-1",
"type": "state",
"occurred_at": "2026-01-15T09:00:00Z",
"data": {
"entity_id": "pump-a",
"status": "Warning",
"temperature": 84
}
}
]
}Request schema
{
"type": "object",
"required": [
"stream",
"events"
],
"properties": {
"stream": {
"type": "string",
"example": "telemetry"
},
"namespace": {
"type": "string",
"description": "Optional searchable metadata. It does not select the workspace."
},
"site_id": {
"type": "string",
"example": "site-sydney-01"
},
"source_id": {
"type": "string",
"example": "edge-node-01"
},
"events": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"id",
"type",
"occurred_at",
"data"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"data": {
"description": "Any valid JSON value."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Responses
202 — Durably accepted; poll verify_url until status is verified
{
"description": "Durably accepted; poll verify_url until status is verified",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"receipt_id",
"status",
"accepted",
"verify_url",
"integrity"
],
"properties": {
"receipt_id": {
"type": "string",
"example": "req_0123456789abcdef"
},
"status": {
"type": "string",
"const": "accepted"
},
"verification_status": {
"type": "string",
"enum": [
"pending",
"unavailable"
]
},
"submitted": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"duplicates": {
"type": "integer"
},
"verify_url": {
"type": "string"
},
"integrity": {
"type": "object",
"properties": {
"algorithm": {
"type": "string"
},
"event_set_sha256": {
"type": [
"string",
"null"
]
}
}
}
}
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"Idempotent-Replayed": {
"description": "true when an existing completed receipt is replayed.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
}
}400 — Validation failed
{
"description": "Validation failed",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}401 — Invalid API key
{
"description": "Invalid API key",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}403 — Missing scope
{
"description": "Missing scope",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}409 — Idempotency key is already being processed
{
"description": "Idempotency key is already being processed",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"Retry-After": {
"description": "Wait at least this many seconds before retrying.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}413 — Payload exceeds 1 MB
{
"description": "Payload exceeds 1 MB",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}429 — Rate limit exceeded
{
"description": "Rate limit exceeded",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"Retry-After": {
"description": "Wait at least this many seconds before retrying.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}503 — Ingest service is temporarily unavailable
{
"description": "Ingest service is temporarily unavailable",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}GET /v1/receipts/{receiptId}Verify that an accepted write is retained and queryable without corruption
Receipts are workspace- and environment-scoped. The endpoint compares every submitted event ID and canonical payload digest with native searchable history. Receipt metadata is retained for 24 hours and does not duplicate customer payloads.
Parameters
[
{
"name": "receiptId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^req_[a-f0-9]{16}$"
}
}
]Responses
200 — Accepted, projecting, verified, conflict, or verification-unavailable state
{
"description": "Accepted, projecting, verified, conflict, or verification-unavailable state",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
}
}400 — Invalid receipt ID
{
"description": "Invalid receipt ID",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}401 — Invalid API key
{
"description": "Invalid API key",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}403 — Missing events:read or events:write scope
{
"description": "Missing events:read or events:write scope",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}404 — Receipt does not exist in this workspace and environment
{
"description": "Receipt does not exist in this workspace and environment",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}429 — Rate or concurrency limit exceeded
{
"description": "Rate or concurrency limit exceeded",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"Retry-After": {
"description": "Wait at least this many seconds before retrying.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}503 — Verification service is temporarily unavailable
{
"description": "Verification service is temporarily unavailable",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}POST /v1/searchSearch events inside the API key workspace
Request example
{
"query": "pump-a",
"namespace": "my-demo",
"from": "now-24h",
"to": "now",
"limit": 10
}Request schema
{
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"namespace": {
"type": "string",
"description": "Optional metadata filter; it never selects the workspace."
},
"from": {
"type": "string",
"default": "now-24h"
},
"to": {
"type": "string",
"default": "now"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"additionalProperties": false
}Responses
200 — Workspace-scoped search results
{
"description": "Workspace-scoped search results",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
}
}400 — Invalid query
{
"description": "Invalid query",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}401 — Invalid API key
{
"description": "Invalid API key",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}403 — Missing events:read scope
{
"description": "Missing events:read scope",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}429 — Rate limit exceeded
{
"description": "Rate limit exceeded",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"Retry-After": {
"description": "Wait at least this many seconds before retrying.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}503 — Search service is temporarily unavailable
{
"description": "Search service is temporarily unavailable",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}POST /v1/queryQuery current state or bounded history using structured field conditions
The API key selects the workspace. Conditions may target canonical fields or validated nested payload.* paths; request fields cannot override tenant scope.
Request example
{
"source": "current",
"where": {
"namespace": "my-demo"
},
"fields": [
"id",
"payload.status"
],
"limit": 10
}Request schema
{
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"current",
"history"
],
"default": "current"
},
"where": {
"type": "object",
"maxProperties": 32,
"additionalProperties": {
"oneOf": [
{
"type": [
"string",
"number",
"boolean",
"null"
]
},
{
"type": "object",
"description": "One operator: eq, ieq, neq, in, not_in, gt, gte, lt, lte, exists, contains, or prefix.",
"additionalProperties": true
}
]
}
},
"fields": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Return only these canonical, payload.*, or metrics.* fields.",
"items": {
"type": "string",
"maxLength": 256
}
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 100
}
},
"additionalProperties": false
}Responses
200 — Tenant-scoped structured query results
{
"description": "Tenant-scoped structured query results",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
}
}400 — Invalid or unbounded history query
{
"description": "Invalid or unbounded history query",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}401 — Invalid API key
{
"description": "Invalid API key",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}403 — Missing events:read scope or query exceeds retention
{
"description": "Missing events:read scope or query exceeds retention",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}429 — Rate or concurrency limit exceeded
{
"description": "Rate or concurrency limit exceeded",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"Retry-After": {
"description": "Wait at least this many seconds before retrying.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}503 — Query service is temporarily unavailable
{
"description": "Query service is temporarily unavailable",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}POST /v1/analyzeAnalyze arbitrary event data and build Hybrid AI decision context
Runs tenant-scoped analysis over current state or bounded history. Custom fields use payload.* or metrics.* paths. Hybrid AI decision mode rejects unverified and out-of-scope fields, collapses repeated observations, and returns deterministic token-budgeted facts, state transitions, contradictions, missing evidence, decision readiness, compaction metrics and proof references.
Request example
{
"source": "current",
"where": {
"namespace": "my-demo"
},
"text": "What is pump-a status and temperature?",
"limit": 10,
"include_results": true,
"context": {
"mode": "decision",
"token_budget": 4000
}
}Request schema
{
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"current",
"history"
],
"default": "history"
},
"where": {
"type": "object",
"maxProperties": 32,
"additionalProperties": true
},
"text": {
"type": "string",
"maxLength": 500
},
"aggregations": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"op"
],
"properties": {
"op": {
"type": "string",
"enum": [
"count",
"distinct",
"sum",
"avg",
"min",
"max",
"integral"
]
},
"field": {
"type": "string",
"maxLength": 256
},
"time_field": {
"type": "string",
"maxLength": 256,
"default": "timestamp",
"description": "Timestamp path used by integral."
},
"unit": {
"type": "string",
"enum": [
"ms",
"s",
"m",
"h"
],
"default": "h",
"description": "Time unit for the integral result."
},
"max_gap_ms": {
"type": "integer",
"minimum": 1,
"maximum": 86400000,
"default": 300000,
"description": "Maximum duration attributed to one sampled value."
}
},
"additionalProperties": false
}
},
"group_by": {
"type": "array",
"maxItems": 8,
"items": {
"type": "string"
}
},
"group_limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 100
},
"time_bucket": {
"type": "object",
"required": [
"interval"
],
"properties": {
"field": {
"type": "string",
"default": "timestamp"
},
"interval": {
"type": "string",
"pattern": "^\\d+(?:ms|s|m|h|d)$",
"example": "5m"
}
},
"additionalProperties": false
},
"vector": {
"type": "object",
"description": "Feature-vector semantic ranking over arbitrary event content.",
"properties": {
"text": {
"type": "string",
"maxLength": 32768
}
}
},
"temporal": {
"type": "object",
"description": "Return source event IDs immediately before and after ranked anchors.",
"properties": {
"before": {
"type": "integer",
"minimum": 0,
"maximum": 50
},
"after": {
"type": "integer",
"minimum": 0,
"maximum": 50
}
}
},
"relationship_fields": {
"type": "array",
"maxItems": 16,
"items": {
"type": "string"
}
},
"relationship_limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 100
},
"context": {
"type": "object",
"properties": {
"token_budget": {
"type": "integer",
"minimum": 256,
"maximum": 100000,
"default": 4000
},
"mode": {
"type": "string",
"enum": [
"documents",
"decision"
],
"default": "documents",
"description": "Use decision to receive admitted, source-backed decision evidence instead of raw source documents."
},
"include_documents": {
"type": "boolean",
"default": false
},
"max_facts": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
},
"max_timeline": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 16
},
"max_contradictions": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 12
},
"contradiction_window_ms": {
"type": "integer",
"minimum": 0,
"maximum": 120000,
"default": 5000
},
"expected_freshness_ms": {
"type": "integer",
"minimum": 1000,
"maximum": 31536000000,
"default": 900000
}
},
"additionalProperties": false
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 100
},
"scan_limit": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"default": 10000
},
"excluded_document_ids": {
"type": "array",
"maxItems": 4096,
"description": "Optional source document IDs to exclude from this analysis request.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"include_results": {
"type": "boolean",
"default": true,
"description": "Include the ranked source-record array alongside the Context Pack."
}
},
"additionalProperties": false
}Responses
200 — Analysis with completeness, freshness, aggregation and source evidence
{
"description": "Analysis with completeness, freshness, aggregation and source evidence",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"execution_mode",
"complete",
"scanned",
"elapsed_ms"
],
"properties": {
"success": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"current",
"history"
]
},
"execution_mode": {
"type": "string",
"enum": [
"optimized",
"semantic",
"bounded"
],
"description": "Stable public execution category. Internal planner details are not exposed."
},
"complete": {
"type": "boolean",
"description": "False when scan_limit was reached and more matching history may exist."
},
"scanned": {
"type": "integer"
},
"filtered": {
"type": "integer"
},
"matched": {
"type": "integer"
},
"elapsed_ms": {
"type": "number"
},
"freshness": {
"type": "object",
"additionalProperties": true
},
"aggregations": {
"type": "object",
"additionalProperties": true
},
"groups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"relationships": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"temporal_windows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"context": {
"type": "object",
"description": "Token-budgeted source records or a compact Hybrid AI packet containing a deterministic context ID, decision readiness, admitted facts, exclusion counts, timeline, contradictions, missing evidence, compaction metrics, confidence and proof IDs.",
"properties": {
"schema_version": {
"type": "string",
"description": "Version of the returned Context Pack contract."
},
"audit_trace_id": {
"type": "string",
"description": "Present only on sampled requests when private native compiler auditing is enabled. Operators can use it to locate the access-restricted trace; no public trace-download endpoint is provided."
},
"proof": {
"type": "object",
"description": "Source references supporting the returned Context Pack. This completeness value is separate from the top-level scan completeness value.",
"properties": {
"complete": {
"type": "boolean"
},
"event_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"results": {
"type": "array",
"description": "Source evidence in the authoritative order returned by Jylus.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"evidence_rank": {
"type": "integer",
"minimum": 1,
"description": "Jylus evidence-selection rank retained for traceability. Consume the result array in its returned order."
},
"source_roles": {
"type": "array",
"description": "Machine-readable state or evidence roles supported by this source record.",
"items": {
"type": "string"
}
},
"proof_digest": {
"type": "string"
},
"relevance": {
"type": "object",
"properties": {
"score": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
}
}
},
"additionalProperties": false
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
}
}400 — Invalid or unbounded analysis
{
"description": "Invalid or unbounded analysis",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}401 — Invalid API key
{
"description": "Invalid API key",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}403 — Missing events:read scope or analysis exceeds retention
{
"description": "Missing events:read scope or analysis exceeds retention",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}429 — Rate or concurrency limit exceeded
{
"description": "Rate or concurrency limit exceeded",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"Retry-After": {
"description": "Wait at least this many seconds before retrying.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}503 — Analysis service is temporarily unavailable
{
"description": "Analysis service is temporarily unavailable",
"headers": {
"X-RateLimit-Limit": {
"description": "API-key plan limit for this operation per minute.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Remaining requests in this operation window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "Window reset time as Unix seconds.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Limit": {
"description": "Plan concurrency limit; present after lease acquisition.",
"schema": {
"type": "integer"
}
},
"X-Concurrency-Active": {
"description": "Active operation leases at acquisition.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}Shared error schema
{
"type": "object",
"required": [
"statusCode",
"statusMessage"
],
"properties": {
"statusCode": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"statusMessage": {
"type": "string"
},
"message": {
"type": "string"
},
"data": {
"description": "Optional validation details or retry metadata.",
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": true
}The reference describes the data APIs. Administrative history and private compiler trace downloads are not public API endpoints.