Log in

Agent Integration

Use this page when an LLM, agent, workflow runner, or other automated client needs to understand how to work with Global Mosaic without crawling private product surfaces or spending quota by accident.

Discovery order

Agents should use these sources in order:

  1. GET /llms.txt for the public map of agent-readable resources.
  2. GET /docs/agents for safety and workflow rules.
  3. GET /api/explain for the sanitized machine-readable API contract.
  4. Gated customer docs only when the user is signed in with an eligible account.

Do not crawl the full website to infer hidden capabilities. Public discovery is the supported contract for unauthenticated agents.

Public machine contract

GET/api/explainnone

Returns the public, sanitized machine-readable API contract for building requests. It omits customer-only catalog detail, lineage, source storage, worker internals, dormant layers, and private operational notes.

Use the public contract to learn the current endpoint list, required top-level fields, location options, response shape, and safe examples. Treat the contract as the source of truth over copied examples.

Authenticated material

Account-specific API detail is intentionally not part of public agent discovery. Agents may use gated customer docs or authenticated catalog responses only when:

  • The user explicitly asks for customer/account-specific integration help.
  • The user is already signed in or supplies an API key through a secure secret mechanism.
  • The request requires customer-specific categories, parameter options, or lineage.

Never place API keys in URLs, browser-visible links, screenshots, logs, support messages, or generated code samples.

Calling the API

Global Mosaic API requests are asynchronous:

  1. Build one request using the current public or authenticated contract.
  2. Ask for confirmation before sending a metered request unless the user has already authorized the workflow.
  3. Send POST /api/invoke with the API key in the x-api-key header.
  4. Store the returned job_id.
  5. Wait for poll_after_seconds.
  6. Poll GET /api/jobs/{job_id} with the same API key.
  7. Stop when the job status is complete or failed.

Do not send a second invoke request just because a job is still queued or running.

Retry rules

SituationAgent behavior
A job_id was returnedStore it and poll the existing job.
Network failed before a responseRetry once only after checking the workflow's own request fingerprint.
Validation failedRepair the request before retrying.
Auth, account, or entitlement failedAsk the user to fix access; do not retry automatically.
Quota failedStop and ask the user before any further metered action.
Job completed with layer errorsInspect partial results and explain which parts failed.

Output rules

  • Say that returned values are modeled, derived, or aggregated estimates unless a customer contract says otherwise.
  • Include job_id, timestamp, selected categories, geography label, and error codes when preparing support handoff text.
  • Do not claim every requested category succeeded until result.errors has been checked.
  • Do not infer account entitlements from public docs.
  • Do not publish customer-only catalog details into public artifacts.