Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Review Queue

Manage private-preview external write proposals: inspect staged connector payloads, approve or reject delivery, and monitor each proposal through final status.

External write proposal review is in private preview and is available only in enabled workspaces and environments.

The review queue API lets authorized reviewers manage external write proposals - staged write-backs to external clinical systems that require human approval before delivery.

Separate approval workflow. External write proposals are created by review-enabled connector sinks. Configuring a Platform Integration's approval_policy does not populate this queue; conversation-scoped integration calls use the endpoints documented in Approval-Gated Integration Writes. In the current Console, this private-preview connector surface is labeled Outbound Write Approvals; the operator-shell Review Queue is a separate patient-facing Surface approval queue.

All endpoints are workspace-scoped and require authentication with an API key or session token that carries the appropriate ReviewQueue permissions.

Endpoints

List external write proposals

List External Write Proposals

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
sort_bystring[]OptionalDefault: []
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
statusstring · enum · nullableOptionalPossible values:
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/external-write-proposals
GET /v1/{workspace_id}/external-write-proposals HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "connector_type": "text",
      "data_source_id": "123e4567-e89b-12d3-a456-426614174000",
      "fhir_resource_type": "text",
      "fhir_resource_id": "text",
      "proposed_payload": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "confidence": 1,
      "origin_run_id": "text",
      "origin_run_kind": "text",
      "origin_event_id": "123e4567-e89b-12d3-a456-426614174000",
      "event_type": "text",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "proposed",
      "decided_by": "123e4567-e89b-12d3-a456-426614174000",
      "decided_at": "2026-01-01T00:00:00.000Z",
      "reject_reason": "text",
      "push_attempt_count": 0,
      "vendor_resource_id": "text",
      "error": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Returns a paginated list of external write proposals, newest first.

Permissions: Requires ReviewQueue:View.

Get external write proposal

Get External Write Proposal

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
proposal_idstring · uuidRequired
Responses
200

Successful Response

application/json

A human-review proposal for an external (EHR) write-back — the Review Queue.

Staged by connector-runner when a review_required sink would otherwise auto-push (world.external_write_proposals); a reviewer approves/rejects, and the egress drain delivers approved ones. proposed_payload is the full FHIR write body and MAY contain PHI — this surface is workspace-scoped (FORCE-RLS) and permission-gated (ReviewQueue); never log it. connector_type/fhir_*/ status/idempotency_key are opaque strings; the ids are uuid.

idstring · uuidRequired
workspace_idstring · uuidRequired
connector_typestringRequired
data_source_idstring · uuidRequired
fhir_resource_typestringRequired
fhir_resource_idstring · nullableOptional
confidencenumber · nullableOptional
origin_run_idstring · nullableOptional
origin_run_kindstring · nullableOptional
origin_event_idstring · uuidRequired
event_typestring · nullableOptional
entity_idstring · uuid · nullableOptional
statusstring · enumRequiredPossible values:
decided_bystring · uuid · nullableOptional
decided_atstring · date-time · nullableOptional
reject_reasonstring · nullableOptional
push_attempt_countintegerOptionalDefault: 0
vendor_resource_idstring · nullableOptional
errorstring · nullableOptional
created_atstring · date-time · nullableOptional
updated_atstring · date-time · nullableOptional
get/v1/{workspace_id}/external-write-proposals/{proposal_id}
GET /v1/{workspace_id}/external-write-proposals/{proposal_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "connector_type": "text",
  "data_source_id": "123e4567-e89b-12d3-a456-426614174000",
  "fhir_resource_type": "text",
  "fhir_resource_id": "text",
  "proposed_payload": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "confidence": 1,
  "origin_run_id": "text",
  "origin_run_kind": "text",
  "origin_event_id": "123e4567-e89b-12d3-a456-426614174000",
  "event_type": "text",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "proposed",
  "decided_by": "123e4567-e89b-12d3-a456-426614174000",
  "decided_at": "2026-01-01T00:00:00.000Z",
  "reject_reason": "text",
  "push_attempt_count": 0,
  "vendor_resource_id": "text",
  "error": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Returns a single external write proposal by ID.

Permissions: Requires ReviewQueue:View.

Approve external write proposal

Approve External Write Proposal

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
proposal_idstring · uuidRequired
Responses
200

Successful Response

application/json

A human-review proposal for an external (EHR) write-back — the Review Queue.

Staged by connector-runner when a review_required sink would otherwise auto-push (world.external_write_proposals); a reviewer approves/rejects, and the egress drain delivers approved ones. proposed_payload is the full FHIR write body and MAY contain PHI — this surface is workspace-scoped (FORCE-RLS) and permission-gated (ReviewQueue); never log it. connector_type/fhir_*/ status/idempotency_key are opaque strings; the ids are uuid.

idstring · uuidRequired
workspace_idstring · uuidRequired
connector_typestringRequired
data_source_idstring · uuidRequired
fhir_resource_typestringRequired
fhir_resource_idstring · nullableOptional
confidencenumber · nullableOptional
origin_run_idstring · nullableOptional
origin_run_kindstring · nullableOptional
origin_event_idstring · uuidRequired
event_typestring · nullableOptional
entity_idstring · uuid · nullableOptional
statusstring · enumRequiredPossible values:
decided_bystring · uuid · nullableOptional
decided_atstring · date-time · nullableOptional
reject_reasonstring · nullableOptional
push_attempt_countintegerOptionalDefault: 0
vendor_resource_idstring · nullableOptional
errorstring · nullableOptional
created_atstring · date-time · nullableOptional
updated_atstring · date-time · nullableOptional
post/v1/{workspace_id}/external-write-proposals/{proposal_id}/approve
POST /v1/{workspace_id}/external-write-proposals/{proposal_id}/approve HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "connector_type": "text",
  "data_source_id": "123e4567-e89b-12d3-a456-426614174000",
  "fhir_resource_type": "text",
  "fhir_resource_id": "text",
  "proposed_payload": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "confidence": 1,
  "origin_run_id": "text",
  "origin_run_kind": "text",
  "origin_event_id": "123e4567-e89b-12d3-a456-426614174000",
  "event_type": "text",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "proposed",
  "decided_by": "123e4567-e89b-12d3-a456-426614174000",
  "decided_at": "2026-01-01T00:00:00.000Z",
  "reject_reason": "text",
  "push_attempt_count": 0,
  "vendor_resource_id": "text",
  "error": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Approves a proposal that is currently in proposed status. The reviewer identity is derived from the authenticated session.

Error responses:

Status
Condition

403

Caller has no authenticated user identity (e.g., an API key without a bound person identity).

404

Proposal not found in this workspace.

409

Proposal is no longer in proposed status (already decided or claimed by the delivery engine).

Permissions: Requires ReviewQueue:Review.

Reject external write proposal

Reject External Write Proposal

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
proposal_idstring · uuidRequired
Body
reasonstring · min: 1 · max: 1000Required
Responses
200

Successful Response

application/json

A human-review proposal for an external (EHR) write-back — the Review Queue.

Staged by connector-runner when a review_required sink would otherwise auto-push (world.external_write_proposals); a reviewer approves/rejects, and the egress drain delivers approved ones. proposed_payload is the full FHIR write body and MAY contain PHI — this surface is workspace-scoped (FORCE-RLS) and permission-gated (ReviewQueue); never log it. connector_type/fhir_*/ status/idempotency_key are opaque strings; the ids are uuid.

idstring · uuidRequired
workspace_idstring · uuidRequired
connector_typestringRequired
data_source_idstring · uuidRequired
fhir_resource_typestringRequired
fhir_resource_idstring · nullableOptional
confidencenumber · nullableOptional
origin_run_idstring · nullableOptional
origin_run_kindstring · nullableOptional
origin_event_idstring · uuidRequired
event_typestring · nullableOptional
entity_idstring · uuid · nullableOptional
statusstring · enumRequiredPossible values:
decided_bystring · uuid · nullableOptional
decided_atstring · date-time · nullableOptional
reject_reasonstring · nullableOptional
push_attempt_countintegerOptionalDefault: 0
vendor_resource_idstring · nullableOptional
errorstring · nullableOptional
created_atstring · date-time · nullableOptional
updated_atstring · date-time · nullableOptional
post/v1/{workspace_id}/external-write-proposals/{proposal_id}/reject
POST /v1/{workspace_id}/external-write-proposals/{proposal_id}/reject HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "reason": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "connector_type": "text",
  "data_source_id": "123e4567-e89b-12d3-a456-426614174000",
  "fhir_resource_type": "text",
  "fhir_resource_id": "text",
  "proposed_payload": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "confidence": 1,
  "origin_run_id": "text",
  "origin_run_kind": "text",
  "origin_event_id": "123e4567-e89b-12d3-a456-426614174000",
  "event_type": "text",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "proposed",
  "decided_by": "123e4567-e89b-12d3-a456-426614174000",
  "decided_at": "2026-01-01T00:00:00.000Z",
  "reject_reason": "text",
  "push_attempt_count": 0,
  "vendor_resource_id": "text",
  "error": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Rejects a proposal that is currently in proposed status. The reviewer identity is derived from the authenticated session.

Error responses:

Status
Condition

403

Caller has no authenticated user identity.

404

Proposal not found in this workspace.

409

Proposal is no longer in proposed status.

Permissions: Requires ReviewQueue:Review.

Proposal lifecycle

Proposals move through the following states:

  1. proposed - Staged by the connector system, awaiting human review.

  2. approved - A reviewer approved the proposal. Awaiting delivery.

  3. rejected - A reviewer rejected the proposal. Will not be delivered.

  4. pushing - The delivery engine is actively sending the write to the external system.

  5. pushed - Successfully delivered to the external system.

  6. failed - Delivery reached a permanent failure, exhausted its retry attempts, or was blocked because retrying could create an unsafe duplicate write.

  7. superseded - Reserved by the response schema. The current public routes do not transition proposals into this state.

Only proposals in proposed status can be approved or rejected. Attempting to decide a proposal in any other status returns a 409 Conflict response.

Concurrency safety

The approve and reject endpoints use guarded state transitions. If two reviewers attempt to decide the same proposal simultaneously, only one succeeds. The other receives a 409 Conflict response and should reload the queue to see the current state.

Audit logging

Every approval or rejection is audit-logged with the connector type, resource type, and reviewer identity. The proposed payload is never included in audit log entries.

PreviousApproval-Gated Integration WritesNextExternal Integrations

Last updated

Was this helpful?