Developer documentation

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
Create a workspace
The Developer tier includes 1 GB and does not require a card.
2
Create a scoped API key
Use a write key for ingest and a read key for search or query workloads.
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.

You stay in control.Create the workspace yourself and provide the key only when the agent asks for it. Review the changed files and tests before deployment.

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.

Get the API key Review the API map

API map

Four production-path operations.

POST /api/v1/events

Ingest 1-100 events per request with idempotent writes and stream identity.

POST /api/v1/search

Discover matching identity, metadata and event content when the structure is not known in advance.

POST /api/v1/query

Retrieve current state or bounded history using exact operators, fields and ordering.

POST /api/v1/analyze

Combine filters, text, vectors, relationships, time and token-budgeted evidence preparation.

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.

Acknowledgement is explicit.The response identifies accepted and duplicate events. Delivery receipts can be checked independently when a durable acknowledgement is required.

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.

Enable managed NATSRequest access from the Developer Hub for the workspace that will own the events.

Store the issued valuesPut the URL, NKey seed and subject in a server-side secret store.

Publish with a stable IDReuse the same message ID when retrying after a timeout or reconnect.

Wait for the ACKDelete buffered data only after js.publish() returns a JetStream acknowledgement.

# 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);

Jylus manages the stream.Do not create a stream or consumer from application code. Jylus provisions retention, replication, limits and subject permissions.

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.

Docker logs

Read container JSON logs through a read-only mount and preserve a local delivery queue.

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

OpenTelemetry

Keep your existing instrumentation. Applications send normal OTLP to 127.0.0.1:4317 or 127.0.0.1:4318; only the Collector talks to Jylus.

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

Need sustained streaming ingest?Use the managed NATS JetStream configuration above. HTTPS remains the default transport and uses separate workspace API keys.

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.

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

{
  "success": true,
  "complete": true,
  "scanned": 1000,
  "matched": 24,
  "elapsed_ms": 18.21,
  "execution_mode": "semantic",
  "context": {
    "context_efficiency": {
      "source_tokens_estimated": 74414,
      "retained_evidence_tokens_estimated": 1892,
      "estimated_token_reduction_percent": 97.46
    },
    "proof": { "complete": true }
  },
  "results": [{
    "id": "evt_01JYLUS9A2",
    "timestamp": "2026-08-20T00:00:00Z",
    "relevance": { "score": 0.94 }
  }]
}

No-match is explicit.A complete result with matched: 0 and an empty result set is a valid no-match, not an API failure. When complete is false, narrow the time range or scope before treating absence as evidence.

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.

Ready to test

Use the awkward workload, not the easy one.

Start free, send real data and compare the returned evidence with the source.

Get a free API key

From first event to answer-ready evidence.