Developer & Integrator FAQ (SDK, Retrieval & Provenance)
Access assumption: This FAQ is written for external developers who integrate over HTTPS. You do not need (and will not receive) access to CueCrux’s internal Docker network or private repos; everything routes through the public Web API or your own BFF that proxies those endpoints.
1. How does the CueCrux SDK differ from the public API client?
External developers install the same @cuecrux/sdk packages published on npm. These clients expose the stable Web API surfaces (/v1/answers, /v1/search, receipts, provenance) with strong typing, retries, and provenance helpers so you can run entirely over HTTPS. Internal operator tooling layers additional admin-only routes (WatchCrux audits, OpsCrux controls) that stay gated behind CueCrux’s private network. If you need one of those advanced surfaces, request it through your account team and it will be proxied for you; you never need direct Engine network access.
2. How do I call the Engine securely from my application?
All Engine calls must flow through a Backend-for-Frontend (BFF) to prevent credential exposure. The BFF injects server-side credentials, enforces usage limits, and adds user/org headers. The SDK provides typed wrappers, retry strategies, timeout guards, and compatibility enforcement. This architecture ensures safe multi-tenant operation and blocks direct client-side misuse.
3. How do I verify receipts programmatically?
The SDK exposes ed25519 verification helpers that confirm receipt signatures and quote-hash matches over the same public Web API you already use. Developers can:
- reload evidence
- validate content hashes
- inspect deterministic seeds
- inspect QUORUM (MiSES) evidence sets (MiSES)
This ensures that an answer is not just correct but provably assembled. For enterprise or regulated contexts, these helpers integrate into audit pipelines or CI checks to ensure system integrity.
4. How do I ingest my private documents for retrieval?
Developers ingest private documents using FactoryCrux’s authenticated ingestion endpoints. Uploads are scanned, parsed, chunked, embedded, and signed into the provenance ledger. Once complete, they become first-class artefacts the Engine can cite. If licensing or robots restrictions prevent processing, FactoryCrux falls back to metadata-only mode to maintain compliance. Developers can then query retrieval with filters/weights to prioritise internal documents.
5. How does CueCrux manage version drift or API mismatches?
Every service exposes /healthz containing build.version, commit, sdkVersion, and compat.requires. WatchCrux monitors these continuously. If drift exceeds tolerance (e.g., major version mismatch, invalid SDK range), it raises alerts and may block releases. The SDK enforces client-side compatibility too, preventing integrators from accidentally depending on outdated Engine contracts.
6. Can I run agents or workflows programmatically?
Yes. AgentCrux provides RPC endpoints and Temporal queues allowing developers to trigger Researcher, Triage, Planner, Budgeter, Auditor, and Release agents. Each run produces an accountability trail, including receipts and intent records. External partners access these flows through the Web API or managed queues provisioned by CueCrux; no internal Docker network, VPN, or repo access is required. Developers can embed these workflows into their own automation or CI/CD processes while keeping credentials and compute inside their environment.
7. Do I ever need direct access to CueCrux’s private infrastructure?
No. Everything in this FAQ assumes you integrate over HTTPS via the Web API or your own BFF that proxies it. CueCrux operates the Engine, WatchCrux, and FactoryCrux planes inside its private network; you interact with them through authenticated API calls, signed receipts, and downloadable artefacts. If you need a new capability (for example, a queue for async agent runs), your account team will expose it as an API surface; you never tunnel into CueCrux infrastructure yourself.