MIMIC API (0.0.0)

Pin a tenant to a different executor class (compute pool). Operations-only — not something a tenant can do to itself. The target tenant is named by the X-Tenant-ID header, as with every other cross-tenant Operations call.

Repointing a tenant's class reassigns where all of its jobs are routed, with no cross-class fallback (ADR-0020). In-flight jobs already assigned to an executor are not touched; jobs still pending in the queue pick up the new class on the next assignment attempt.

The class is validated as a slug. If no executor is currently registered for the target class, the change still succeeds, but the response carries a warning — the tenant's jobs will queue until a matching pool is provisioned. This is intentional: Operations sometimes repoints a tenant ahead of standing up its pool.

Authorization: requires the mimic:write:tenants_mgmt scope, granted only to the qvyon-ops role. The handler additionally rejects any non-Operations caller.

Returns 400 if executor_class is malformed. Returns 404 if the X-Tenant-ID header names an unknown tenant.

Opens an import of one sequence folder from the caller's machine. The full file list is announced here and checked before anything is sent: scene.json at the folder's root, paths that stay inside the folder, no path twice, each file at most 5 GiB, at most 50 GiB in total.

The files are written directly to object storage with presigned URLs (see POST /{import_id}/urls), into a folder of their own -- the one the sequence will live in. Close with POST /{import_id}/complete.

Authorization (requires mimic:write:validations scope):

• Admin Users: Opens in their tenant (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Opens in the specified tenant. X-Tenant-ID header required.

List sequence imports for the authenticated tenant, in every status.

Pass status to filter to imports currently in any of the given statuses.

Authorization (requires mimic:read:validations scope):

• Admin Users: Lists imports in their tenant (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Lists imports in the specified tenant. X-Tenant-ID header required.

Retrieve a single sequence import by ID. Does not look at object storage -- see /resume for that.

Authorization (requires mimic:read:validations scope).

Returns 404 if not found.

Cancels an UPLOADING import: no validation run is created, and the files received so far are deleted shortly after. A COMPLETED import is left alone -- its files are the sequence's now; delete the validation instead.

Authorization (requires mimic:write:validations scope).

Idempotent: returns 204 even if already cancelled, expired, completed or not found.

Checks that object storage holds exactly the announced files at the announced sizes, then creates the sequence's validation run in READY_TO_VALIDATE, with the import's object_uri. Call the validations :start to run it.

Safe to retry: on an import already COMPLETED, returns its validation again.

Authorization (requires mimic:write:validations scope).

Returns 400 if a file is missing, has another size, or was not announced (one error per file, the first 100); 404 if the import is not found, CANCELLED or EXPIRED.

Compares object storage with the announced files and returns those still missing (or at another size, e.g. overwritten by a stray PUT), so an interrupted upload -- even one whose caller lost its own record of what was sent -- picks up where it stopped. Refreshes uploaded_files/uploaded_bytes and pushes expires_at back.

Authorization (requires mimic:write:validations scope).

Returns 404 if the import is not UPLOADING.

Returns a presigned PUT URL for each path given, valid for 15 minutes. Each URL is bound to its file's key and announced size: the PUT must carry that exact Content-Length. Ask in batches as the upload goes rather than for every file at once -- a URL that expires before it is used is simply asked for again. Pushes expires_at back.

Authorization (requires mimic:write:validations scope).

Returns 400 if a path was not announced, 404 if the import is not UPLOADING.

Creates one validation run record per sequence given, in order, in READY_TO_VALIDATE -- no job is created and no executor is involved yet. The manual counterpart to :scan for a caller that already knows a sequence's name and object_uri rather than discovering it by walking the landing zone -- sequences must be non-empty. Call :start to actually dispatch the validation jobs.

Authorization (requires mimic:write:validations scope):

• Admin Users: Creates validations in their tenant (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Creates validations in the specified tenant. X-Tenant-ID header required.

List validation runs for the authenticated tenant.

Pass job_id to look up the validation run created by a specific validation job -- useful for clients (e.g. a generic jobs list) that only know the job ID and need to poll its progress.

Pass name to filter by a case-insensitive substring match on the sequence's name.

Pass tag_ids to filter to validations tagged with any of the given tags.

Pass executor_version to filter to validations whose job reported that exact executor version.

Pass status to filter to validations currently in any of the given statuses.

Pass created_at_from and/or created_at_to to filter to validations whose created_at falls within that inclusive range.

Pass sort_by to choose the sort column.

Authorization (requires mimic:read:validations scope):

• Admin Users: Lists validations in their tenant (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Lists validations in the specified tenant. X-Tenant-ID header required.

Returns the URI of the tenant's staging directory -- a fixed location, not something a caller chooses. Drop raw sequences there, then call :scan to discover them.

Authorization (requires mimic:read:validations scope):

• Admin Users: Returns their own tenant's staging directory (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Returns the specified tenant's staging directory. X-Tenant-ID header required.

Attach every listed tag to every listed validation, so that a multi-row selection produces one request instead of one per pair.

Authorization (requires mimic:write:tags scope).

Idempotent: pairs that are already attached are left alone. Returns 404 if any tag or validation does not exist.

Detach every listed tag from every listed validation.

Authorization (requires mimic:write:tags scope).

Idempotent: pairs that are not attached are left alone. Returns 404 if any tag or validation does not exist.

Returns every distinct executor_version recorded across this tenant's validation runs (e.g. for a UI filter dropdown) -- looks through the executor_version reported on every Validation, not just the latest.

Empty list if no run has reported a version yet, including when there are no validations at all.

Authorization (requires mimic:read:validations scope).

Retrieve a single validation run by ID.

Authorization (requires mimic:read:validations scope):

• Admin Users: Can only read validations in their tenant. X-Tenant-ID header ignored.
• Operations Users: Can read validations in any tenant. X-Tenant-ID header required.

Returns 404 if not found or soft-deleted.

Soft-delete a validation run, matching Reconstruction/Actor's delete semantics.

If the underlying job is still QUEUED, ASSIGNED, or RUNNING, it is cancelled first before the validation run is soft-deleted. Otherwise (VALID, INVALID, ERROR, READY_TO_VALIDATE, already CANCELLED) it is soft-deleted directly. Sequence files the platform stores (imported or scanned in) are then permanently deleted.

Returns 409 while any reconstruction of it still exists (delete those first), or while a job built on this sequence is still winding down -- deleting would pull the files out from under them.

Authorization (requires mimic:write:validations scope):

• Admin Users: Can delete validations in their tenant. X-Tenant-ID header ignored.
• Operations Users: Can delete validations in any tenant. X-Tenant-ID header required.

Idempotent: returns 204 even if already deleted or not found.

Step 1 of the pipeline: scans the tenant's staging directory (see GET /import-directory), walking its directory tree for scene.json files. For each one found, the immediate parent directory name becomes the sequence's name and its S3 path becomes its object_uri.

Validations are the system's registry of sequences -- there is no separate registration step. A validation run is created directly for each newly discovered sequence, in READY_TO_VALIDATE. Sequences already known (matched by object_uri) are skipped, so repeated (re-)scans are safe -- only genuinely new sequences produce new records.

No job is created and no executor is involved yet -- call :start to actually dispatch the validation jobs.

Authorization (requires mimic:write:validations scope):

• Admin Users: Scans their tenant's staging directory (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Scans the specified tenant's staging directory. X-Tenant-ID header required.

Starts the validation job for each validation run ID given, in order -- validation_ids must be non-empty. Unlike Actor's per-resource :start, this is bulk: a validation job takes no per-item args, so one request can start many runs at once.

Eligible starting statuses: READY_TO_VALIDATE (first run), or VALID/INVALID/ERROR/ CANCELLED (to retry or re-run) -- so a caller can bulk-retry a set of failed or cancelled validations in one call. Not eligible while a run is already in flight (QUEUED, VALIDATING).

Authorization (requires mimic:write:validations scope):

• Admin Users: Can only start validations in their tenant. X-Tenant-ID header ignored.
• Operations Users: Can start validations in any tenant. X-Tenant-ID header required.

Returns 409 if any validation run is not in an eligible status.

Create a reconstructed model record without starting anything -- no job is created and no executor is involved. The model starts in READY_TO_RECONSTRUCT. Call :start to actually dispatch the reconstruction job.

This lets a caller (e.g. the Mimic UI, transitioning between pipeline stages) create the record ahead of time without committing to run it yet.

Authorization (requires mimic:write:reconstructions scope):

• Admin Users: Creates the reconstruction in their tenant (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Creates the reconstruction in the specified tenant. X-Tenant-ID header required.

Supports Idempotency-Key header for safe retries.

List reconstructed models for the authenticated tenant.

Default sort: created_at DESC, reconstruction_id ASC (newest first, stable tie-breaker). Includes models in all statuses (PROCESSING, READY, FAILED). Excludes soft-deleted models.

Pass job_id to look up the reconstruction created by a specific training job — useful for clients (e.g. a generic jobs list) that only know the job ID and need to poll its progress/metrics/output_uri.

Pass name to filter by a case-insensitive substring match on the model's name.

Pass tag_ids to filter to models tagged with any of the given tags.

Pass executor_version to filter to models whose job reported that exact executor version.

Pass status to filter to models currently in any of the given statuses.

Pass started_at_from and/or started_at_to to filter to models whose started_at falls within that inclusive range.

Pass sort_by to choose the sort column.

Authorization (requires mimic:read:reconstructions scope):

• Admin Users: Lists reconstructions in their tenant (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Lists reconstructions in the specified tenant. X-Tenant-ID header required.

Returns the parameters accepted by POST /reconstructions's args field, derived from the ReconstructionArgs schema, so a client can render a form without hardcoding field names.

Static schema only — does not resolve per-scene default values.

Authorization (requires mimic:read:reconstructions scope).

Attach every listed tag to every listed reconstruction, so that a multi-row selection produces one request instead of one per pair.

Authorization (requires mimic:write:tags scope).

Idempotent: pairs that are already attached are left alone. Returns 404 if any tag or reconstruction does not exist.