Runtime integration

Send reliable execution evidence from any HTTP-capable application.

The REST ingestion contract is language-neutral. Keep its credential in the monitored runtime, deliver telemetry out of band, and never let a monitoring-network failure change the workload's result.

1. Issue a workspace ingestion credential

Open Workspace integration. An owner or administrator can issue a credential with a descriptive deployment or environment name.
Copy the plaintext once. Store it immediately in the runtime's secret manager. LatidoFlow stores only a hash and the final four characters for identification.
Send it only in the Authorization header. Use Authorization: Bearer <token>. Never place it in a query string, log, MCP configuration, or source file.

Management OAuth and ingestion credentials are separate. OAuth authorizes a customer or agent to manage allowlisted resources; an ingestion credential lets a runtime synchronize definitions and submit execution evidence.

2. Synchronize stable monitor definitions

Send explicit project, environment, and monitor slugs. Reusing a slug updates the same logical definition. Use heartbeat for externally reported work or uptime for a public HTTPS check.

curl -X POST "https://www.latidoflow.com/api/v1/monitors/sync" \
  -H "Authorization: Bearer ${LATIDOFLOW_INGESTION_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "project": {"name": "Billing", "slug": "billing"},
    "environment": {
      "name": "Production",
      "slug": "production",
      "kind": "production",
      "is_production": true
    },
    "monitors": [{
      "name": "Invoice synchronization",
      "slug": "invoice-sync",
      "type": "heartbeat",
      "check_interval_minutes": 15,
      "grace_seconds": 120,
      "timeout_seconds": 900,
      "is_active": true
    }]
  }'

Save the returned project, environment, and monitor UUIDs when your client uses UUID-based routes. Definition sync proves configuration, not execution.

3. Report the logical run lifecycle

Queued

POST /api/v1/runtime/runs/queued

Record a durable queue intent by project, environment, and monitor slugs.

Started

POST /api/v1/runtime/runs/start

Start by stable slugs, or use /api/v1/monitors/{monitorUuid}/runs/start when the UUID is already configured.

Progress

POST /api/v1/runs/{runUuid}/heartbeat

Refresh a long-running execution before its timeout.

Succeeded

POST /api/v1/runs/{runUuid}/success

Finish only after the business postcondition passes; include bounded output or evidence when required.

Failed

POST /api/v1/runs/{runUuid}/fail

Finish only after retry exhaustion. Send a constant safe category, never the raw exception.

Skipped

POST /api/v1/runtime/runs/skipped

Advance an expected schedule window without fabricating a successful run.

Logs

POST /api/v1/runs/{runUuid}/logs

Append bounded, redacted diagnostic events when they add useful evidence.

POST /api/v1/runtime/runs/start
Authorization: Bearer <workspace-ingestion-token>
Idempotency-Key: invoice-sync:2026-08-09T16:00:00Z
Content-Type: application/json

{
  "project_slug": "billing",
  "environment_slug": "production",
  "monitor_slug": "invoice-sync",
  "source": "python_worker"
}

Capture the returned run_uuid and use it for progress, logs, and the terminal outcome. Reuse the same idempotency key when retrying the same logical event; generate a new key for a new logical run.

4. Keep telemetry off the business path

Deliver out of band

Append telemetry intent to a local outbox, sidecar, or dedicated worker. A remote LatidoFlow call must not delay or fail the customer workload.

Preserve queue semantics

Use one opaque logical key across retry and redelivery. Do not emit terminal failure for an intermediate retry or from an unconditional cleanup block.

Bound and redact

Send numeric aggregates and safe state labels. Exclude credentials, personal data, raw payloads, provider responses, queries, URLs, and stack traces.

Handle responses deliberately

Correct 401 credentials, 404 scope, 409 state, and 422 contract errors. Retry transient network, rate-limit, or server failures only out of band with bounded backoff.

5. Verify the integration

Workspace integration shows separate milestones for credential issuance, definition synchronization, and accepted runtime evidence.
The monitor detail page contains the natural execution with the expected source, state, timestamps, output, and semantic-check result.
A later replay with the same idempotency key does not create a second logical run.
The workload still succeeds or fails according to its own business logic when LatidoFlow delivery is unavailable.

Open workspace integration OpenAPI 3.1 contract Agent setup