Skip to content

Publish a lookup service

A lookup resolves caller inputs against an approved on-demand source. It does not accept customer observation or event ingestion.

Before you start

An operator must first register the source adapter through the reviewed source workflow and sync it into QuickLookup. The adapter must have Result grain = Lookup and expose its input and output schema.

See Sources and FDW for the approval and health checks.

Create the lookup

  1. Create or reuse a source binding with Mode = On demand and select the lookup adapter.
  2. Set fixed parameters, cache TTL, and source page size. These may narrow the adapter capabilities but cannot widen them; public response paging is independent.
  3. Open Provision → Lookup services → Add lookup service.
  4. Enter the service identity, description, access policy, classifications, and provenance.
  5. Select the binding and its lookup contract.
  6. Save, clear every Ready to publish? blocker, and run the bounded preview.
  7. Publish and wait for delivery.

The contract is the UI contract. Inputs with enumerated choices render as dropdowns; dates, numbers, booleans, and arrays render with matching controls. Alternative input groups appear as separate resolution methods.

Verify it

  1. Find it with GET /v1/catalog/services?type=lookup.
  2. Follow detailUrl; verify the accepted inputs, alternatives, output fields, defaults, and source page capacity.
  3. Send a returned example to queryUrl.
  4. Confirm source, reused, fetchedAt, and freshUntil match the source and cache behavior you configured.

The older /v1/lookups endpoints expose the adapter-oriented compatibility interface. New clients should use the unified service directory and queryUrl, which apply the published service contract and access policy.

Handle source failure

An unavailable adapter returns 503 unless a result is still reusable under the binding's cache policy. Check Sources → Source adapters for the health state and last sanitized error. Repair the provider or FDW relation, sync from CTX if its schema changed, and retry the same bounded query.