Bulk Import (Migration)

Bulk-import terminal Classic conversation metadata for migrated person entities.

The migration operation imports terminal Classic conversation metadata for existing person entities so migrated history can appear in supported world-model conversation views.

It is admin-only, accepts up to 500 conversations per request, and is idempotent and correctable for a workspace and source conversation ID. It imports conversation metadata rather than transcript turns and does not emit world events for the memory extractor.

Import Conversation Metadata

Bulk-import v1 conversation envelopes for migrated patients

post

Writes one terminal world.conversations row per v1 conversation (real dates, provider='v1-migration'), giving the returning-user greeting and the real conversation list. Admin-only, idempotent + correctable per (workspace, v1 conversation id), memory-safe (no world events emitted → the memory extractor never re-derives from these). Transcript content (turns) is a separate follow-up. Batch size <= 500.

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

Body

Responses

200

Successful Response

application/json

importedintegerRequired

createdintegerRequired

updatedintegerRequired

400

Naive/future timestamps, bad window, or non-person entity_id.

403

Insufficient permissions.

422

Validation Error

application/json

post/v1/{workspace_id}/world/migration/conversations

POST /v1/{workspace_id}/world/migration/conversations HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 218

{
  "conversations": [
    {
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "source_conversation_id": "text",
      "started_at": "2026-01-01T00:00:00.000Z",
      "ended_at": "2026-01-01T00:00:00.000Z",
      "channel_kind": "web",
      "turn_count": 0
    }
  ]
}

{
  "imported": 1,
  "created": 1,
  "updated": 1
}

Use a stable source conversation ID so corrections update the imported record instead of creating duplicates. Timestamps must be timezone-aware, terminal, and internally ordered. Retry only after reconciling the response counts for the prior request.