Agent twin request contract 1.7¶

GET and POST /twin return request contract 1.7. This version adds customer_tier to each item, with one of three values: bronze, silver, or gold. The default is bronze.

Endpoints and authentication¶

Base URL: https://app.carveragents.ai/api/v1/agent-compliance. Send an enabled, approved super-admin API key in X-API-Key.

Method and path	Effect
`GET /twin`	Preview matching twins without changing state.
`POST /twin`	Claim matching twins and mark them `in_progress`.
`POST /twin/outputs`	Submit a full assessment. Its result contract versions independently.

GET accepts query parameters. POST accepts equivalent JSON filters: status, kind_type, organization_id, agent_id, twin_version_id, created_since, updated_before, and limit. GET also accepts offset. The default limit is 50; the maximum is 200. There is no customer_tier filter or tier-setting input on these endpoints.

The default status is pending. GET can also preview in_progress and completed; POST can claim pending or reclaim in_progress. Use updated_before with an ISO-8601 timestamp containing a timezone to reclaim stale work. Twins in incomplete, gtm_pending, or gtm_failed are excluded. Soft-deleted twins and deleted or disabled agents are excluded.

export CARVER_API_KEY='YOUR_SUPER_ADMIN_API_KEY'
export CARVER_BASE='https://app.carveragents.ai/api/v1/agent-compliance'

curl --fail-with-body --silent --show-error \
  -H "X-API-Key: $CARVER_API_KEY" \
  "$CARVER_BASE/twin?status=pending&kind_type=obligations&limit=10"

curl --fail-with-body --silent --show-error \
  -X POST -H "X-API-Key: $CARVER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"status":"pending","kind_type":"obligations","limit":10}' \
  "$CARVER_BASE/twin"

Response schema¶

Both methods return the same envelope:

{
  "contract_version": "1.7",
  "items": [],
  "total": 0
}

The outer contract_version is present even for an empty queue. Each item also carries contract_version: "1.7". GET's total counts matching twins before pagination; POST's total counts the twins actually claimed.

Item field	Type	Meaning
`contract_version`	string	`"1.7"`.
`customer_tier`	string enum	`"bronze"`, `"silver"`, or `"gold"`. Always supplied; never null. Stored per agent.
`metadata`	object	Submission metadata from the linked lead; `{}` without a linked lead. Preserve unknown keys.
`gtm_obligations`	object or null	Stored preliminary quick brief, with its own content schema version. Older twins can have null.
`request_id`	string or null	Mapping-run identifier. Echo the claimed value when posting results.
`agent_id`	string	Agent UUID.
`twin_version`	integer	Version of the agent description.
`twin_version_id`	string	UUID of this twin row.
`kind_type`	string or null	Assessment artifact, usually `"obligations"`. Filter for the kind your worker handles.
`scope`	object or null	Existing entitlement scope, normally `{ "name": "free" or "paid", "limits": {...} }`. Empty limits mean no configured caps.
`created_at`, `updated_at`	timestamp string or null	Twin creation and latest state-update timestamps.
`input`	object	Submitted agent facts, including routing fields and description. Backend provenance and document bookkeeping are omitted.

customer_tier is a top-level field alongside scope; it is not injected into input. It is independent of scope.name and does not change free/paid product entitlements or scope limits. The assessment service decides how customer tier affects assessment behavior.

The existing routing fields agent_id, twin_version, and kind_type also remain inside input. environment, system_context, and organization_context remain in input. Organization context comes from the submitted twin; the organization's business profile is not used as a fallback. Top-level metadata and gtm_obligations are separate from input facts. The preliminary brief must not be treated as the complete assessment or as confirmed legal applicability. See the quick-brief contract for its content schema.

Example item¶

This fictional example uses placeholder identifiers and a legacy twin without a stored quick brief. Both GET and POST return this item shape.

{
  "contract_version": "1.7",
  "items": [
    {
      "contract_version": "1.7",
      "customer_tier": "gold",
      "metadata": {},
      "gtm_obligations": null,
      "request_id": "req_example_run_2",
      "agent_id": "e4c57bec-0825-4099-b407-48c313da1120",
      "twin_version": 1,
      "twin_version_id": "323c17d9-eed1-41b5-9706-035f5733dd7c",
      "kind_type": "obligations",
      "scope": {"name": "paid", "limits": {}},
      "created_at": "2026-10-16T12:00:00+00:00",
      "updated_at": "2026-10-16T12:05:00+00:00",
      "input": {
        "agent_id": "e4c57bec-0825-4099-b407-48c313da1120",
        "twin_version": 1,
        "kind_type": "obligations",
        "environment": "production",
        "system_context": null,
        "organization_context": {},
        "description": "A billing assistant that drafts invoices for staff review.",
        "serves": ["DE"]
      }
    }
  ],
  "total": 1
}

Tier assignment and reassessment¶

New organizations default to bronze. New agents copy their organization's current default tier. Organization default changes affect future additions; existing agents keep their assigned tiers. When a funnel agent is claimed into an existing organization, it inherits a higher destination tier while retaining any higher individual tier already granted.

Super admins can change an agent's tier in Admin dashboard → All Agents. Changing a tier in either direction:

Saves the agent's tier.
Resets current mapping work in pending, in_progress, or completed to pending, with a fresh request_id. All artifacts at the latest live twin version are considered; historical twin versions remain unchanged.
Retains the previous mapping while the new assessment runs.
Rings the assessment doorbell after the transaction commits, for active agents.

Selecting the existing tier makes no change and does not ring the doorbell. An agent still in intake or quick-brief generation keeps its existing workflow state and uses the new tier when ready. A disabled agent stays disabled and does not ring the doorbell. A failed doorbell notification does not undo the saved change; pending work remains available for the assessment service's next poll.

The description's twin_version does not increase for a tier change. Workers must echo the request_id from the claim they processed. A supplied request ID that no longer matches the stored run receives HTTP 409 on /twin/outputs.

Super admins can change an organization's default in Organizations → select organization → Info → Default customer tier. This does not requeue existing agents.

Admin write APIs¶

These dashboard endpoints require a super-admin bearer access token. They are separate from the API-key-authenticated mapper endpoints above.

Method and path	JSON body	Effect
`PATCH /api/v2/ismyagentlegal/admin/agents/{agent_id}/customer-tier`	`{"customer_tier":"gold"}`	Changes an individual tier and requeues eligible work.
`PATCH /api/v2/core/organizations/{organization_id}`	`{"customer_tier":"silver"}`	Changes the default for future agent additions.

The agent endpoint returns agent_id, customer_tier, changed, requeued, and status. requeued: true means mapping work was reset to pending; it does not mean a disabled agent's doorbell was rung. Invalid enum values receive 422; callers without super-admin access cannot change tiers.

Migration from 1.6¶

Accept request contract_version: "1.7" on both the envelope and each item, and read the new top-level customer_tier. Consumers retaining queued 1.6 payloads can treat a missing tier as bronze for compatibility. Live 1.7 responses always include it. All other request fields retain their existing meaning.

This is the outbound twin request version. The external full-assessment result contract remains 1.8, the output acknowledgement remains response_schema_version: "1.2", and stored quick briefs retain their own schema_version. Do not copy request version 1.7 into an independently versioned result document. The integer input schema version is unchanged.

The backend release includes organization and agent field migrations; existing rows receive bronze. Apply these migrations with the backend deployment, and rebuild the backend and admin dashboard to expose the new contract and controls.