Engineers

Runtime integration: authorise first, execute second

This page describes a minimal integration pattern to gate AI‑initiated real‑world actions with Tradedly. Platforms must hard‑block execution unless decision=permitted.

1) Preflight

Authorisation

Request permission for a specific action. Receive a decision, constraints, and an audit reference.

POST /v1/platform/authorisations

2) Attempt

Execution attempt

Only if permitted: create a time‑boxed attempt and record evidence events.

POST /v1/platform/attempts

3) Evidence

Audit events

Fetch immutable audit events for governance, compliance, and customer proof.

GET /v1/platform/audit/{audit_id}/events

Non‑negotiables

Decision enforcement: execution must not proceed unless decision=permitted.
Idempotency: supply Idempotency-Key on preflight and attempt calls to prevent duplicates.
Safe-by-default: responses must not expose provider identity, rankings, routing logic, or internal notes.
Attempts-not-outcomes: a refused or failed attempt is a valid terminal state and must be logged as evidence.

Example preflight

curl -X POST https://tradedly.com/v1/platform/authorisations   -H "content-type: application/json"   -H "x-api-key: ***"   -H "idempotency-key: intent_uk_claim_902113_action_1"   -d '{
    "intent_id": "intent_uk_claim_902113_action_1",
    "customer_id": "tenant_uk_insurer_01",
    "agent_id": "claims_triage_agent_v3",
    "action_type": "real_world_action",
    "domain": "claims_property",
    "region": "london",
    "constraints": {
      "sla_minutes": 60,
      "max_retries": 0,
      "requires_human_ack": false
    }
  }'

Machine-readable assets: /platforms-integration.json · /openapi.yaml · PDF: Platform Integration Pack