From first event to answer-ready evidence.

Quickstart

Send a real event in minutes.

Create a free workspace, create a server-side key with events:write, then send the request below. Keep API keys out of browser code and source control.

1. 1
   Create a workspace

   The Developer tier includes 1 GB and does not require a card.

2. 2
   Create a scoped API key

   Use a write key for ingest and a read key for search or query workloads.

3. 3
   Replace the sample payload

   Jylus accepts nested JSON without requiring a customer-specific schema.

curl https://api.jylus.ai/api/v1/events \
  --request POST \
  --header "Authorization: Bearer $JYLUS_API_KEY" \
  --header "Idempotency-Key: evt_01JYLUS9A2" \
  --header "Content-Type: application/json" \
  --data '{
    "stream": "telemetry-production",
    "events": [{
      "id": "evt_01JYLUS9A2",
      "type": "model.completed",
      "occurred_at": "2026-08-20T00:00:00Z",
      "data": { "latency_ms": 8.7, "model": "example-model" }
    }]
  }'

Expected 202 Accepted response

{
  "request_id": "req_0123456789abcdef",
  "receipt_id": "req_0123456789abcdef",
  "status": "accepted",
  "verification_status": "pending",
  "submitted": 1,
  "accepted": 1,
  "duplicates": 0,
  "verify_url": "/api/v1/receipts/req_0123456789abcdef",
  "durability": { "acknowledged": true }
}

AI-agent quickstart

Let your coding agent wire Jylus into the application.

Give an AI coding agent the official docs and a bounded implementation task. It can inspect the existing data shape, add the correct API path and validate the integration without putting a workspace key in source control.

Integrate this application with Jylus using the official developer docs at https://jylus.ai/docs.

Preserve existing behavior. First identify the application's event and data shape. Ask me for a Jylus API key only when it is required; keep it server-side and never write it to source control, client code, output or logs.

Send one idempotent event to POST /api/v1/events and verify the accepted response. Retrieve it with the appropriate Search or Query API. If this application uses an AI model, add POST /api/v1/analyze and pass only the returned Context Pack to the model.

Run the relevant tests and show me the files changed.

API map

Four production-path operations.

Ingest

Send the JSON your application already emits.

Every event needs a stable ID, type and occurrence time. Put workload-specific fields under data; retries with the same idempotency key are safe.

Managed streaming

Stream events with managed NATS JetStream.

Builder and higher plans can use a managed JetStream publisher for sustained ingest. Jylus issues a TLS URL, an NKey seed and a workspace-restricted publish subject; these are separate from HTTPS API keys.

# Issued in the Developer Hub when managed NATS is enabled
JYLUS_NATS_URL=tls://<issued-host>:4222
JYLUS_NATS_NKEY_SEED=<issued-NKey-seed>
JYLUS_NATS_SUBJECT=<issued-workspace-subject>

import { connect, nkeyAuthenticator } from "@nats-io/transport-node";
import { jetstream } from "@nats-io/jetstream";

const encoder = new TextEncoder();
const nc = await connect({
  servers: process.env.JYLUS_NATS_URL,
  authenticator: nkeyAuthenticator(
    encoder.encode(process.env.JYLUS_NATS_NKEY_SEED)
  ),
  tls: {}
});

const js = jetstream(nc);
const eventId = crypto.randomUUID();
const ack = await js.publish(
  process.env.JYLUS_NATS_SUBJECT,
  encoder.encode(JSON.stringify({
    id: eventId,
    type: "model.completed",
    occurred_at: new Date().toISOString(),
    data: { latency_ms: 8.7 }
  })),
  { msgID: eventId }
);

console.log(ack.stream, ack.seq);

Connectors

Connect Docker and OpenTelemetry.

The downloadable collectors keep credentials in local secret files, buffer through temporary outages and deliver through the same tenant-scoped HTTPS ingest path.

mkdir -p jylus-edge/secrets && cd jylus-edge
curl -fsSLO https://jylus.ai/downloads/jylus-edge-agent.compose.yml
printf '%s' "$JYLUS_WRITE_API_KEY" > secrets/jylus-api-key
chmod 600 secrets/jylus-api-key
docker compose -f jylus-edge-agent.compose.yml up -d

mkdir -p jylus-otel/secrets && cd jylus-otel
curl -fsSLO https://jylus.ai/downloads/jylus-opentelemetry-collector.compose.yml
curl -fsSLO https://jylus.ai/downloads/jylus-opentelemetry-collector.yaml
printf '%s' "$JYLUS_WRITE_API_KEY" > secrets/jylus-api-key
chmod 600 secrets/jylus-api-key
docker compose -f jylus-opentelemetry-collector.compose.yml up -d

Search API

Find data before you know every field.

Use search for incident phrases, identifiers and cross-structure discovery. Add a namespace and bounded time range whenever the scope is known.

curl https://api.jylus.ai/api/v1/search \
  --request POST \
  --header "Authorization: Bearer $JYLUS_READ_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "checkout timeout payment declined",
    "from": "now-24h",
    "to": "now",
    "limit": 25
  }'

Structured query

Retrieve exact fields when the question is exact.

Query current state or retained history using safe nested field paths and explicit operators. Projection keeps responses small.

curl https://api.jylus.ai/api/v1/query \
  --request POST \
  --header "Authorization: Bearer $JYLUS_READ_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source": "current",
    "where": {
      "payload.service.name": { "eq": "checkout" },
      "payload.deployment.region": { "in": ["ap-southeast-2"] }
    },
    "fields": ["timestamp", "payload.service.name", "payload.release.version"],
    "order": "desc",
    "limit": 100
  }'

Hybrid AI

Prepare evidence for the model's token budget.

Combine structured scope, lexical intent and semantic retrieval in one request. Decision mode returns bounded facts, timeline evidence, freshness and proof metadata without requiring the LLM to read every source document.

The API key selects the workspace and data plane. For source: history, provide a lower time bound in where.timestamp. vector.text accepts up to 32,768 characters on the live v1 API.

curl https://api.jylus.ai/api/v1/analyze \
  --request POST \
  --header "Authorization: Bearer $JYLUS_READ_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source": "history",
    "where": { "timestamp": { "gte": "now-24h" } },
    "text": "authentication failures after a release",
    "vector": { "text": "users cannot sign in following deployment or policy change" },
    "context": {
      "mode": "decision",
      "token_budget": 2000,
      "max_facts": 18,
      "max_timeline": 12,
      "include_documents": false
    },
    "scan_limit": 1000,
    "limit": 24
  }'

Read the returned Context Pack (illustrative fields and values)

{
  "success": true,
  "complete": true,
  "execution_mode": "semantic",
  "context": {
    "schema_version": "1.1",
    "proof": {
      "complete": true,
      "event_ids": ["evt_01JYLUS9A2"]
    }
  },
  "results": [{
    "id": "evt_01JYLUS9A2",
    "timestamp": "2026-08-20T00:00:00Z",
    "evidence_rank": 1,
    "source_roles": ["status", "transition"],
    "relevance": { "score": 0.94 }
  }]
}

MCP for agents

The existing evidence engine, connected to your agent.

Connect over standard Streamable HTTP at https://api.jylus.ai/api/mcp using Authorization: Bearer <read-only API key>. The key selects the workspace and environment. No second retrieval engine or model is involved.

Open the MCP setup page for OpenAI Responses API, Claude API, Gemini CLI, Cursor and Node.js configuration. MCP API-key authentication requires events:read; OAuth sign-in is not included in this release.

get_context_pack

Required question; optional namespace, safe where filters, from/to, token_budget (256-16,000; default 2,000), and limit (1-100; default 24). The time window defaults to the last 24 hours, within plan retention.

resolve_state

Required question, ISO from and ISO as_of, including timezone. Supports the same scope and budget options. Passes both effective and knowledge cutoffs to Jylus and excludes later source observations. The history must include the applicable policy/state evidence.

get_evidence

Required event_ids (1-20 exact source IDs); optional namespace and from/to. Copy IDs from context.proof.event_ids, not the decision-context ID. Supply the source time window; otherwise only the last 24 hours is searched.

{
  "name": "get_context_pack",
  "arguments": {
    "question": "What changed in the last 24 hours?",
    "namespace": "my-events",
    "from": "now-24h",
    "token_budget": 2000
  }
}

Responses contain the unmodified public API evidence under structuredContent and as JSON text for older clients. Tool errors set isError; failures are never returned as a successful no-match. Requests are limited to 64 KiB and upstream calls have a 45-second deadline. HTTP 401/403 denies access; 421 indicates the wrong region; 429 requires a delayed retry.

Evidence and audit

Follow the source behind a decision.

Read results in returned order. A result can carry evidence_rank, source_roles and proof_digest. In decision mode, context.proof.event_ids identifies source records used in the Context Pack; facts can carry their own proof_ids. Use those IDs to inspect the retained source record. The decision context ID identifies the pack, not a source citation.

Reliability and security

Design reliable retries and protect keys.

• Use a stable event ID and idempotency key for every retryable write.
• Wait for the HTTPS response or JetStream publish acknowledgement before deleting buffered data.
• Use separate least-privilege keys for write and read workloads.
• Never send a workspace key to browsers, public repositories or client-side mobile code.
• Keep source copies or backups for data that must remain recoverable.

API reference and clients

Use the public v1 contract.

Explore the interactive API reference, or download the canonical OpenAPI 3.1 specification for the authenticated events, receipt, search, query and analyze routes. Import it into Postman or an OpenAPI client generator. A ready-to-import Postman collection is also available. Keys belong in your server environment, never in a browser.

Download a minimal Node.js client example or Python client example. Both call the ordinary public API; neither bundles the proprietary engine or adds a model. Pass a source scope in where and inspect context.decision_readiness, missing evidence and proof IDs before answering.

Analyze limits

Context output: 256–100,000 estimated tokens (4,000 default); up to 100 facts, 100 timeline items, 16 relationship fields and 1,000 relationships. A history request requires a lower timestamp bound within plan retention.

Rate limits and retries

X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset describe the current window. For HTTP 429, wait for Retry-After. Do not immediately fan out retries.

Errors

400: invalid request; 401: missing or invalid authentication; 403: permission or entitlement denied; 429: rate or concurrency limit; 5xx: service failure. Retain the response's request/incident identifier when requesting support.

Write idempotency

Completed ingest reservations are retained for 24 hours. Keep both the same event IDs and Idempotency-Key when retrying an unchanged batch, and verify the receipt rather than assuming acceptance means evidence is ready.

Delivery and versioning

Use the receipt's verify_url to poll durable delivery. This guide does not promise a general webhook API. The documented public routes use /api/v1; request any contractual deprecation notice requirements from support.