Import

Track import runs for migrations from Simply Plural, PluralKit, and Octocon. Each run records status, progress, and per-entity counts (directories, members, entries, front sessions) while data is copied into your Florality account.

Base path: /api/v1/import. Scope: import: read for GET routes, read_write for POST / PATCH. See Authentication and Scopes.

Public REST exposes run lifecycle only (create row, poll, update progress). Cancel, delete, purge-by-source, and import-map queries are not on public REST.

Concepts

• Import run: one attempt to migrate data. Starts as running; ends completed or failed.
• Summary: counts per entity type: created, skipped, failed, optional updated.
• Progress fields: progressPhase, progressPercent, progressDetail for live UI or automation.
• Source systems: simply_plural, pluralkit, octocon (used when correlating migrated entity ids; not passed on REST start).

Runs are tenant-scoped to the API key user. Timestamps are Unix milliseconds.

Endpoint index

List runs

GET/api/v1/import/runs

Query

Returns ImportRunDoc[].

{
  "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "userId": "a0a0a0a0-a0a0-a0a0-a0a0-a0a0a0a0a0a0",
  "status": "running",
  "startedAt": 1714233600000,
  "finishedAt": null,
  "summary": {
    "directories": { "created": 2, "skipped": 0, "failed": 0, "updated": 0 },
    "members": { "created": 5, "skipped": 1, "failed": 0, "updated": 0 },
    "entries": { "created": 10, "skipped": 0, "failed": 0, "updated": 0 },
    "frontSessions": { "created": 0, "skipped": 0, "failed": 0, "updated": 0 }
  },
  "errorMessage": null,
  "progressPhase": "members",
  "progressPercent": 42,
  "progressDetail": "Importing member 6 of 14"
}

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/import/runs?limit=20"

Get run by id

GET/api/v1/import/runs/{runId}

Returns a single ImportRunDoc, or JSON null when the id is unknown or belongs to another account (200, not 404).

null

Get active run

GET/api/v1/import/active

Most recent run with status: "running", or null. No query parameters.

Get latest run

GET/api/v1/import/latest

Most recent run by startedAt (any status), or null. No query parameters.

Start run

POST/api/v1/import/start

Creates a new run row with status: "running" and empty summary counters. No request body. 201 with { "runId": "uuid" }.

Your integration should PATCH progress as import work proceeds, then set status to completed or failed with finishedAt.

{
  "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/import/start"

Update run

PATCH/api/v1/import/runs/{runId}

Partial update. All fields optional. 204 on success.

Body fields

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "finishedAt": 1714237200000,
    "summary": {
      "directories": { "created": 5, "skipped": 1, "failed": 0, "updated": 2 },
      "members": { "created": 12, "skipped": 3, "failed": 0, "updated": 1 },
      "entries": { "created": 40, "skipped": 0, "failed": 2, "updated": 0 },
      "frontSessions": { "created": 8, "skipped": 0, "failed": 0, "updated": 0 }
    }
  }' \
  "https://api.floralitys.com/api/v1/import/runs/RUN_UUID"

// 204 No Content: empty response body

Errors

JSON { "code", "message" }:

• UNAUTHORIZED (401): missing/invalid API key
• FORBIDDEN (403): insufficient import scope
• BAD_REQUEST (400): invalid UUID, body, or unknown query param
• NOT_FOUND (404): PATCH when run missing or wrong tenant
• PRECONDITION_FAILED (503): DATABASE_URL not configured

See Errors.

{
  "code": "NOT_FOUND",
  "message": "Import run not found or access denied"
}