Managed HTTP API

Versioned root and authority

The configured HTTPS service root is /api/managed/v1/integrations/{integrationId}. Download OpenAPI 3.1 and the referenced JSON schemas. API description version 1.2.0 includes the canonical displayed-area-authority-v1 decision policy, published presentation reads and the backend request-input descriptor.

A confidential backend uses Authorization: Bearer … with its issued runtime grants. Visitors use X-Overa-Visitor. Exact origin/CORS checks constrain public browser use but are not secret authentication: an Origin header alone cannot authorize a backend call.

Preview bootstrap and Street View admission/outcome operations are also documented in OpenAPI. They require their declared authority and configuration; a website visit or backend runtime grant is not unlimited panorama permission.

A provider-free backend read and facts comparison

This example reads the published profile and compares up to three current items when comparison is enabled. It performs no evaluation, naming or routing. Supply your issued origin, integration and key on the server; the function is not invoked by this page.

export async function readAndCompare({
  origin, integrationId, backendSecret, fetchImpl = fetch,
}) {
  // Call on your server. Read backendSecret from protected storage.
  const host = new URL(origin);
  if (host.protocol !== 'https:' || host.origin !== origin)
    throw new Error('Use the exact configured HTTPS service origin.');
  if (!/^[a-z][a-z0-9-]{0,63}$/.test(integrationId || ''))
    throw new Error('Use your issued integration ID.');
  if (!backendSecret) throw new Error('A backend credential is required.');
  const root = new URL(
    '/api/managed/v1/integrations/' + encodeURIComponent(integrationId), host,
  );
  const headers = { Accept: 'application/json',
    Authorization: 'Bearer ' + backendSecret };
  async function request(url, options = {}) {
    const response = await fetchImpl(url, { ...options,
      headers: { ...headers, ...options.headers } });
    const body = await response.json();
    if (!response.ok) {
      const error = new Error(body.code || 'managed_request_failed');
      error.status = response.status;
      throw error;
    }
    return body;
  }
  const profile = await request(root);
  const itemIds = (profile.items || []).slice(0, 3).map(item => item.id);
  if (!profile.decisionCapabilities?.comparison?.enabled || !itemIds.length)
    return { profile, comparison: null };
  const comparison = await request(new URL(root.pathname + '/comparisons', host), {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ schemaVersion: 'located-item-comparison-request-v1',
      expectedDataRevision: profile.source.dataRevision, itemIds }),
  });
  return { profile, comparison };
}

Additional schemas and agency reports

Download the client-theme schema alongside the managed schema bundle. Register it by its canonical $id in your JSON Schema validator; that identifier is not a customer service origin.

Download Agency Insights OpenAPI 1.0.0 for overview, demand, stock gaps, engagement and conversions. Reporting, export, observation and confirmed conversions require their declared staff or confidential backend grants. Collection and release stay off unless the operator separately authorizes the exact integration, source and policy. Do not infer an enabled report from a view import or general runtime key.

Canonical results

Use the returned pass, miss and unknown outcomes and their reasons. For a valid displayed travel area, inside and boundary points satisfy that spatial requirement, while outside points miss. Exact journey metrics remain supporting evidence. When no valid area exists, the canonical point-metric fallback applies. Property requirements remain independent and can still make an overall result miss.

decisionPolicyVersion names these decision semantics. evaluationVersion names the provider-evidence algorithm, not a substitute policy version. Bind requests to expectedDataRevision; use the server-issued evaluation reference for assessed comparison only within its current caller, integration, source and lifetime. Never convert unavailable evidence into a match.

Errors and recovery

Quotas are operational limits

Setup publishes the supported modes, destination count, source capacity and customer/integration/provider caps. Read these values rather than hard-coding a global allowance. Admission happens before protected work; actual upstream starts, including retries and chunks, consume allowance. Cache hits start no upstream request.

Limits and usage counters are not invoices or complete browser-imagery bandwidth estimates. Cancellation, missing responses or restart do not guarantee a refund of a possible start. Do not automatically retry after a limit, authority failure or cancellation.