Agent mapping response contract 1.5

Contract 1.5 adds a top-level metadata object to each twin returned by both mapping queue endpoints:

• GET /api/v1/agent-compliance/twin — preview matching work without claiming it.
• POST /api/v1/agent-compliance/twin — claim matching work and mark it in_progress.

Both endpoints require X-API-Key credentials with the super_admin role.

Change from 1.4

Field	Version 1.4	Version 1.5
items[].contract_version	"1.4"	"1.5"
items[].metadata	Absent	JSON object; {} when no metadata is available

The response envelope remains { "items": [...], "total": N }. All existing item fields remain unchanged. This is a response contract version change; endpoint URLs stay under /api/v1/.

Metadata semantics

items[].metadata contains the current metadata of the lead linked to that agent. This includes caller-supplied per-agent metadata from JSON bulk uploads and any stored submission context, such as sender_type, device, browser, or referrer. Keys and values are passed through without filtering or renaming; nested objects, arrays, numbers, booleans, and null values are preserved.

Agents without a linked lead, or whose lead has no metadata, return {}. When several agents share a lead, they receive that lead's same metadata. Changes made through the metadata update endpoint appear on subsequent GET previews and POST claims; metadata is read at response time rather than frozen with the twin version.

Metadata sits outside input: it is submission and integration context, separate from the agent facts used for legal assessment. If the twin body itself contains a metadata key, that remains at items[].input.metadata independently.

Example response

Illustrative values below show the shape returned by either endpoint:

{
  "items": [
    {
      "contract_version": "1.5",
      "metadata": {
        "sender_type": "bot",
        "customer_id": "customer-42",
        "tags": ["billing"],
        "integration": { "batch_id": "batch-2026-10-09" }
      },
      "request_id": "req_2026-10-09_abc123def456",
      "agent_id": "11111111-1111-4111-8111-111111111111",
      "twin_version": 1,
      "twin_version_id": "22222222-2222-4222-8222-222222222222",
      "kind_type": "obligations",
      "scope": { "name": "paid", "limits": {} },
      "created_at": "2026-10-09T09:00:00+00:00",
      "updated_at": "2026-10-09T09:00:00+00:00",
      "input": {
        "agent_id": "11111111-1111-4111-8111-111111111111",
        "twin_version": 1,
        "environment": "production",
        "kind_type": "obligations",
        "system_context": null,
        "organization_context": {},
        "description": "A billing chatbot for European customers.",
        "serves": ["DE"]
      }
    }
  ],
  "total": 1
}

The actual input includes the stored twin body, excluding provenance and sources. POST claims update updated_at when work is claimed.

Downstream adoption

1. Accept contract_version: "1.5" in request payload validation.
2. Add metadata as an object with arbitrary JSON properties to the twin item schema.
3. For compatibility with older 1.4 responses, treat a missing metadata field as {}.
4. Read integration context from item.metadata and keep legal assessment facts in item.input.

The result submission endpoint, POST /api/v1/agent-compliance/twin/outputs, retains its existing result contract (1.0). Downstream workers do not need to echo metadata back in mapping results.