Skip to content
Artist Alley

Start a new metadata-extraction backfill run

POST
/admin/metadata-extraction/backfills

Inserts a metadata_backfill_run row + enqueues the coordinator job. The job walks every active image asset matching the scope + enqueues one metadata.extract child per asset. Returns the new run row; progress polls land via GET …/backfills/{id}. Gated on system.admin.

Empty scope = all active image assets. Optional asset_type_ref narrows to one asset type’s population.

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”

Operator-facing input to start a new backfill run. All fields optional — empty body = “all active image assets”.

Filters compose with AND. asset_type_ref (singleton) and asset_type_refs (multi-select) are merged into one IN-list — populating both is equivalent to passing the singleton’s value inside the array.

The file_extensions and include_non_image fields let operators target raws / PDFs without spilling the backfill over their entire image catalogue.

object
asset_type_ref

Narrow to one asset type. Null / omitted = every type.

integer format: int64
nullable
asset_type_refs

Multi-select asset-type filter. Empty / omitted = no asset-type filter from this field; singleton asset_type_ref still applies if set.

Array<integer>
file_extensions

Lowercase file extensions (no leading dot) to include. Empty / omitted = no extension filter. Typical Phase 1.18.A-3.B uses: ["cr2","nef","dng","arw","rw2"] to backfill raw embedded previews, or ["pdf"] to backfill PDF /Info metadata + page counts.

Array<string>
include_non_image

Open the population to non-image assets (PDFs today; comics + ebooks later). Defaults to false so older callers keep the original image-only scope.

boolean

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Run inserted + coordinator job enqueued.

One backfill-coordinator run row. Counters move as the coordinator job walks the population.

object
id
required
string format: uuid
asset_type_ref
integer format: int64
nullable
total
required

Unknown at start (0). Reserved for a future “count first” pre-walk pass; current implementation leaves at 0 and the UI shows ”—” when zero + not-yet-completed.

integer format: int64
processed
required
integer format: int64
succeeded
required
integer format: int64
failed
required
integer format: int64
started_at
required
string format: date-time
completed_at
string format: date-time
nullable
cancelled_at
string format: date-time
nullable
started_by_user_ref
integer format: int64
nullable

401

Section titled “401 ”

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

403

Section titled “403 ”

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed