Minimal Protocol

The protocol a CLI client speaks to Olyx Cloud is intentionally narrow.

The protocol has three responsibilities:

This public protocol covers the CLI control-plane contract. For cloud deployments, Olyx Cloud may retain public or anonymized telemetry according to project policy. For Enterprise private deployments, provider secrets stay customer-side and private payloads are not stored by Olyx Cloud unless the deployment is explicitly configured to allow that boundary.

Trace IDs are opaque UUIDs in the current backend, and replay job IDs are opaque hex strings. Clients should treat both as unlabeled identifiers rather than trying to infer meaning from their shape.

Control Plane Calls

All public protocol calls use HTTPS and a project-scoped API key.

Authorization: Bearer ak_...
Accept: application/json
Content-Type: application/json

The default control-plane URL is:

https://app.olyxai.io

Protocol Sequence

The integration surface is intentionally narrow:

1. GET /api/v1/config to discover policy.
2. POST /api/v1/traces to register a unit of work.
3. Local model or workflow execution in the customer environment.
4. PATCH /api/v1/traces/{trace_id}/complete or POST /api/v1/replay after the work finishes.

Request Conventions

Every request should include:

Authorization: Bearer ak_...
Accept: application/json
Content-Type: application/json
User-Agent: olyx-cli/0.1

Clients should send JSON request bodies and expect JSON responses. Unknown response fields should be ignored so the control plane can add optional fields without breaking older clients.

Idempotency

For operations that create work, send an idempotency key when retrying after a timeout:

Idempotency-Key: trace-create-01J2Z9F7J8S8CZ1K2YQ9M9P7TX

Recommended keys:

If a request times out before a response is received, retry with the same idempotency key instead of creating duplicate work.

Example idempotent trace create:

POST /api/v1/traces
Idempotency-Key: trace-create-checkout-01J6AH...

Discover Configuration

GET /api/v1/config

The endpoint name is kept for compatibility, but CLI clients should read the distribution object.

{
  "offline_testing": false,
  "enterprise_compute": {
    "enabled": false,
    "mode": "standard",
    "compute_backend": "ruby",
    "accelerated_primitives": [],
    "runtime_boundary": "olyx_cloud"
  },
  "guardrails": {
    "max_input_length": 10000,
    "pii_threshold": 0.7,
    "injection_block": true,
    "secret_action": "alert"
  },
  "runtime_failover": {
    "preferred_runtime": "cloud",
    "fallback_order": ["cloud"],
    "edge_fallback": {
      "enabled": false,
      "targets": [],
      "fail_closed": false
    },
    "cloud_fallback": {
      "enabled": true,
      "mode": "cloud-primary",
      "requires_redaction": false,
      "require_customer_kms": false,
      "require_admin_approval": false,
      "raw_payloads_allowed": true,
      "provider_secrets_allowed": false
    },
    "data_boundary": "olyx_cloud",
    "fail_closed": false
  },
  "distribution": {
    "project_id": 123,
    "distribution_channel": "cli",
    "telemetry_mode": "anonymized",
    "payload_storage_mode": "cloud_anonymized",
    "payload_retained": true,
    "replay_execution_mode": "cloud",
    "secrets_boundary": "customer_environment",
    "cloud_payloads": true,
    "local_ref_required": false
  },
  "runtime_activation": {
    "url": "/api/v1/runtime/activation",
    "signature_algorithm": "EdDSA",
    "envelope_format": "jws_compact_json",
    "public_key_distribution": "response_keyring"
  }
}

Clients should fetch configuration during startup and cache it briefly. Refresh the configuration before creating high-volume traces or queueing replay jobs so policy changes are respected.

Recommended cache behavior:

Example startup policy fetch:

curl https://app.olyxai.io/api/v1/config \
  -H "Authorization: Bearer $OLYX_API_KEY" \
  -H "Accept: application/json"

Clients should treat these fields as required for safe public behavior:

Across cloud and enterprise deployments, clients should assume provider credentials remain in the customer environment. The control plane does not require provider API keys in order to issue config, accept traces, or coordinate replay.

Trace Lifecycle

Create a trace:

POST /api/v1/traces

{
  "metadata": {
    "source": "olyx-cli",
    "feature": "support"
  }
}

Response:

{
  "id": "trace_01J6AF...",
  "status": "pending",
  "metadata": {
    "source": "olyx-cli",
    "feature": "support"
  },
  "created_at": "2026-06-03T14:12:09Z",
  "revenue": null,
  "distribution": {
    "distribution_channel": "cli",
    "telemetry_mode": "anonymized",
    "payload_storage_mode": "cloud_anonymized",
    "payload_retained": true,
    "replay_execution_mode": "cloud",
    "local_ref": null
  }
}

Create trace request fields:

Avoid storing unbounded or sensitive values in metadata. If a value is needed for your own replay store, put it behind a local_ref instead.

Recommended metadata keys:

State transitions:

Complete a trace:

PATCH /api/v1/traces/{trace_id}/complete

No request body is required. Trace completion should be called once the local work finishes. The server marks the trace complete and refreshes the computed metrics from the recorded steps.

Retrieve a trace:

GET /api/v1/traces/{trace_id}

Clients should treat trace IDs as opaque strings. Do not parse IDs to infer creation time, project, or storage location.

Replay Lifecycle

Queue a replay:

POST /api/v1/replay

{
  "trace_id": "trace_01J6AF..."
}

Poll a replay job:

GET /api/v1/replay/{job_id}

Replay responses are asynchronous. A job can be queued, running, completed, or failed.

Example queued response:

{
  "job_id": "job_01J6AG...",
  "source_trace_id": "trace_01J6AF...",
  "status": "queued"
}

Example completed response:

{
  "job_id": "job_01J6AG...",
  "source_trace_id": "trace_01J6AF...",
  "status": "completed",
  "summary": {
    "baseline_model": "standard-model",
    "candidate_model": "frontier-model",
    "latency_delta_ms": -120,
    "cost_delta": "0.0008"
  }
}

Polling guidance:

Stop polling on completed, failed, canceled, 401, 403, or 404.

Example polling loop:

for delay in 1 1 2 2 5 5; do
  curl "https://app.olyxai.io/api/v1/replay/${JOB_ID}" \
    -H "Authorization: Bearer $OLYX_API_KEY" \
    -H "Accept: application/json"
  sleep "$delay"
done

Telemetry Modes

Clients should fail closed on unknown telemetry modes and ask the operator to upgrade the CLI.

When telemetry is anonymized, remove or replace:

Practical interpretation:

Validation Rules

Public clients should enforce basic request validation before sending data:

If policy includes max_input_length, validate locally before sending trace payload references or metadata that represents input size.

Fail closed when:

Error Shape

Most errors return:

{
  "error": "message",
  "code": "machine_code",
  "request_id": "request-id"
}

Common status codes:

Example protocol-level auth failure:

{
  "error": "Unauthorized",
  "code": "unauthorized",
  "request_id": "req_01J6AJ..."
}

Retry Rules

What To Read Next

• Quick Start — run the protocol steps interactively in under 5 minutes.
• Policy Schema — full field reference for the config response your client receives.
• Auth — API key formats, scoping, and rotation.
• API Endpoints — complete list of supported operations and request shapes.