---
title: "Import or backfill many profiles"
method: POST
path: "/v1/import/profiles"
tags: ["Import"]
---

# Import or backfill many profiles

`POST /v1/import/profiles`

## Request

- Base URL: `https://api.configure.dev`
- URL: `https://api.configure.dev/v1/import/profiles`
- Auth: API key in header `X-API-Key`

Server-side secret-key-only bulk import for historical dialogue or existing profile artifacts. Import is not a model tool, does not use profile.commit(), and does not write root profile files.

## Headers

- `X-Agent` string

## Request body

- ImportProfilesRequest: Request bodies may not set path, source, written_by, timestamps, or memory IDs.
  - `mode` 'backfill', required
  - `idempotencyKey` string: Scoped to the developer account and acting agent.
  - `users` ImportProfileUser[], required
    - `externalId` string, required: Developer app-local subject ID. It never becomes a storage path.
    - `idempotencyKey` string
    - `profile` object
      - `summary` string
      - `preferences` string[]
      - `facts` string[]
      - `identity` object
    - `conversations` ImportConversation[]
      - `id` string
      - `messages` ImportMessage[], required
        - `role` 'system' | 'user' | 'assistant' | 'tool', required
        - `content` string, required

## Response `200`

Existing idempotent import job returned.

- ImportJob
  - `id` string
  - `mode` 'backfill'
  - `status` 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled'
  - `accepted_profiles` integer
  - `estimated_message_count` integer
  - `estimated_input_chars` integer
  - `imported_memory_count` integer
  - `processed_profile_count` integer
  - `failed_profile_count` integer
  - `quota` object
    - `imported_profiles` ImportQuotaState
      - `used` integer
      - `limit` union
        - integer
        - 'unlimited'
      - `requestedNew` integer
      - `remaining` union
        - integer
        - 'unlimited'
  - `caps` ImportCaps
    - `max_profiles_per_job` integer
    - `max_total_input_chars_per_job` integer
    - `max_concurrent_import_jobs` integer
    - `max_conversations_per_profile` integer
    - `max_messages_per_conversation` integer
    - `max_chars_per_message` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `cancelled_at` string, date-time, nullable

## Other responses

- `202`: Import job queued.
- `402`: Quota exceeded. Import quota failures happen before job creation or raw payload persistence.
- `413`: Payload exceeds a configured cap.
- `422`: Request shape is invalid.
- `429`: Rate or concurrency limit exceeded.

---

[API](https://skmtc.dev/configure/apis/configure-http-api.md) · [All operations](https://skmtc.dev/configure/apis/configure-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/configure/apis/configure-http-api/revisions/ec760a9533d2?raw)