DQ Cloud API (0.1.0)

Agent registers one of its locally-configured datasources.

Agent deregisters one of its datasources.

Agent updates display_metadata on its datasource.

Return up to 20 pending agent-mode jobs that target this agent's datasources. Oldest first so backlog clears in order.

Atomic claim. Returns the dispatch envelope on success; 409 if another agent already won the job (the same agent re-calling will also see 409, on purpose — claim must be idempotent against self).

Accept the redacted metadata payload, write a ValidationResult row, mark the queue row success/failed, fire alert evaluation, audit the call.

Three layers of defence on the payload:

1. Body-size cap (_MAX_COMPLETE_PAYLOAD_BYTES) — even a healthy redacted result is well under 8 KiB; anything bigger is suspicious.
2. :func:validate_redacted_payload — rejects forbidden keys (unexpected_rows, kwargs, value_set, …).
3. :func:_truncate_payload_strings — caps the user-controlled string fields so description-style exfiltration can't fit more than a few hundred chars of customer data.

Then the host-side belt-and-suspenders: the queue row's checkpoint must target one of this agent's own datasources in this principal's workspace (:func:_run_queue_targets_agent).

Mark the queue row failed with the agent-provided error (scrubbed to 2000 chars). Used when the agent can't reach its DB, GX raises, etc.

Roll claimed_at forward so a long-running job doesn't get reclaimed.

Stream the rendered export file.

Authenticated by the HMAC signature in the query string (see :func:services.export_storage.verify_download_token). Deliberately not gated by Depends(get_principal) — the signed URL is the credential, designed to be hand-able to an auditor without forcing them to log into DQ Cloud. The signature expires per the URL's own exp claim; past the expiry, every request returns 410 Gone.

List the org's most recent exports.

Hard-capped at 30 rows — the UI surface is "what's pending and what can I still download", not an audit-trail of every export ever requested. A future GET ?cursor=... would extend this; not in scope here.

Request a new audit-log export.

Inserts an AuditExport row in status='pending' and enqueues run_audit_export on ARQ. Returns 202 with the row + a poll_url (the single-row GET) so the UI can wire up the polling loop without having to construct the URL itself.

Date-range cap is :data:settings.audit_export_max_range_days (default 90). Years-long exports are out of scope; an operator wanting one requests it in 90-day slices.

Single-row status check — used by the UI's poll loop.

Returns the row plus, when status='complete', a freshly-signed download URL. The URL is regenerated on every read (rather than being persisted) so the underlying signing key can be rotated without invalidating already-issued export rows the moment the config flips.

Public, unauthenticated deployment metadata.

Returned fields:

• region — operator-declared region label (DEPLOYMENT_REGION).
• version — the API package version (matches app.version).
• sso_enabled — whether SSO is available at this deployment.
• llm_provider — the default LLM provider, or None when AI is not configured.

Public, unauthenticated build marker (C-84-1).

Returns the commit sha the running API image was built from (stamped per deploy from image_refs.hcl), its short form, the commit timestamp and the package version. The UI shows the same sha in the account menu. A commit sha of an open-source-shaped codebase is not sensitive; nothing else is returned.

Return the static expectation gallery.

Wrapped in {"data": [...]} to match the convention used by every other V1 endpoint — the UI's apiFetch helper unwraps .data uniformly so adding a new endpoint that returns a bare list would be a paper cut.

Which AI features auto-run for this org (asks U4).

Readable by EVERY authenticated org member — unlike ai-policy (LLM managers only) — because every AI panel reads it to decide whether to generate on mount. It exposes no secret and no spend figure, just the per-feature switches: the org's own choice (source="org") or, until an admin saves one, the deployment default (source="deployment").

Save the org's AI auto-run switches (asks U4) — admin-gated.

Same gate as ai-policy (CAN_MANAGE_LLM_CONFIGS): the switches decide whether LLM spend happens without a click, so only the people who manage the org's AI engine may flip them. Not fresh_auth — it flips routing flags, not a credential. Partial: an omitted flag keeps its current value. Audited.

Return the org's stored ai_mode plus deployment native-availability.

native_available lets the UI decide whether to even offer the native toggle (a self-host without Vertex access shows BYOLLM only), and effective_mode is the engine the resolver would pick right now.

Set (or clear, with ai_mode: null) the org's native-vs-BYOLLM override.

Return this org's AI usage aggregated by day + a totals block.

Wire shape::

{
  "data": {
    "window": {"days": 30, "since": "2026-07-18T00:00:00Z"},
    "totals": {
      "requests": 12, "prompt_tokens": 3400, "output_tokens": 900,
      "est_cost_usd": 0.0031,
      "native": {"requests": 10, "prompt_tokens": 3000, "output_tokens": 800, "est_cost_usd": 0.0028},
      "byo":    {"requests": 2,  "prompt_tokens": 400,  "output_tokens": 100, "est_cost_usd": 0.0003}
    },
    "by_day": [
      {"day": "2026-08-16", "requests": 5, "prompt_tokens": 1200,
       "output_tokens": 300, "est_cost_usd": 0.0011}
    ],
    "by_model": [
      {"model": "gemini-3.6-flash", "is_native": true, "requests": 10,
       "prompt_tokens": 3000, "output_tokens": 800, "est_cost_usd": 0.0028}
    ]
  }
}

by_day is ascending by date and includes only days that had usage. Estimated cost is derived at read time from :data:_PRICE_PER_1M (so a price correction re-prices history) and rolled up per day from per-MODEL rates — NOT from an org-wide blended rate — so a day mixing Flash and Pro is priced correctly.