Apply Manifest

Apply a YAML manifest to create resources.

Creates all resources defined in the manifest file in dependency order.

Modes:

• create_only (default) — fails if any resource already exists.
• create_missing — creates what is missing, leaves what exists alone, and resolves manifest references against the resources ALREADY in the namespace. This is what makes “here is a namespace with buckets, add these collections over them” work. Under create_only a reference to an undeclared-but-existing bucket is a validation error, because the manifest is treated as a closed world.

Plan first: before creating anything, apply runs the same checks as POST /v1/manifest/validate. Any error refuses the whole manifest with success: false, every resource skipped, and each error naming the resource, the field and the fix. Nothing is created. A namespace budget above the organization’s bound is set to the bound and reported as a warning.

Features:

• Topological sorting ensures resources are created in correct dependency order
• Secret references (${{ secrets.NAME }}) are resolved from organization secrets
• Atomic operation: rolls back all created resources if any creation fails, and an apply whose process is stopped part way is rolled back when the API starts again
• Dry run returns the plan without making changes

Example:

curl -X POST /v1/manifest/apply \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: ns_xxx" \
  -F "manifest_file=@mixpeek.yaml"

Example manifest:

version: "1.0"
metadata:
  name: "my-environment"

namespaces:
  - name: video_search
    feature_extractors:
      - name: multimodal_extractor
        version: v1

buckets:
  - name: raw_videos
    namespace: video_search
    schema:
      properties:
        video: { type: video }

POST /v1/manifest/apply

Apply Manifest

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/manifest/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form manifest_file=@example-file \
  --form 'parameters=<string>'

200

{
  "created_count": 2,
  "dry_run": false,
  "errors": [],
  "failed_count": 0,
  "resources": [
    {
      "name": "video_search",
      "resource_id": "ns_abc123",
      "resource_type": "namespace",
      "status": "created"
    },
    {
      "name": "raw_videos",
      "resource_id": "bkt_xyz789",
      "resource_type": "bucket",
      "status": "created"
    }
  ],
  "rollback_performed": false,
  "skipped_count": 0,
  "success": true
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

Query Parameters

dry_run · boolean · default: false

Run the plan only: the same checks as POST /v1/manifest/validate, returned as errors and warnings, with nothing created. Each resource reads would_create, or exists when it is already there. Under mode create_only an existing resource refuses the plan, as it would refuse the apply

deadline_seconds · number | null

Wait up to this many seconds after the resources are created for every Ray Serve app a declared collection needs to be RUNNING (the apps listed in readiness). Past the deadline the result has success false and an error naming the deadline and each app not RUNNING; the resources stay in place. Omit to return as soon as the resources exist.

Required range: 1 <= x <= 1800

wait_for_seed · boolean · default: false

After the resources exist, wait until every seed: batch has finished (COMPLETED, COMPLETED_WITH_ERRORS, FAILED or CANCELED), within deadline_seconds or 900 seconds when that is omitted. Each batch's status and documents_written are returned in seed_batches; one that failed or did not finish in time is also named in errors. success still reports resource creation only

run_acceptance · boolean · default: false

Implies wait_for_seed and also waits for the Serve apps in readiness. Then runs the manifest's acceptance: steps in order and returns each in acceptance with passed, expected, observed and error. A step that could not run (deadline reached, seed batch failed, Serve apps not RUNNING) is passed false with the reason. The steps are normal executions in your organization and are billed like any query or inference call; acceptance.max_cost_usd is checked against the meter before each step and at the end. Re-apply with mode=create_missing to re-run the steps on a namespace that already exists without creating anything. A manifest with no acceptance: block is refused with 400

mode · enum<string> · default: create_only

create_only (default): fail if any resource already exists. create_missing: create what is missing and leave what exists alone, which is what lets a manifest be applied to an EXISTING namespace. create_missing does not UPDATE anything — a resource that exists but differs from the manifest is reported as exists and left untouched. upsert: create what is missing AND patch what exists but differs, so re-applying a manifest brings the running resources back to what it declares. Each resource is patched only through its own update surface, so a field that surface does not accept, or refuses the value of, is reported in refused with the resource and the field named, and the rest of the manifest still applies. Explicit on purpose: this is the only mode that CHANGES resources that already exist.

Available options: create_only, create_missing, upsert

Body

multipart/form-data

manifest_file · file · required

YAML manifest file

parameters · string | null

JSON object of values for the manifest's declared parameters, e.g. {"camera_url": "rtsp://host/stream", "polling_seconds": 300}. Each value must match its declared type. Omit when the manifest declares none.

Response

200

application/json

Successful Response

Result of applying a manifest.

success · boolean · required

Whether all resources were created successfully

resources · ResourceResult · object[]

Results for each resource

Show child attributes

created_count · integer · default: 0

Number of resources created

failed_count · integer · default: 0

Number of resources that failed

skipped_count · integer · default: 0

Number of resources skipped

would_create_count · integer · default: 0

On a dry run, the number of resources the real apply would create. Resources that already exist are reported with status exists and are not counted here. Always 0 on a real apply.

updated_count · integer · default: 0

Resources that existed, differed, and were PATCHED to match. Only ever non-zero under upsert. Counted separately because without it an upsert that changed five running resources reports created 0, failed 0, skipped 0, a summary that reads as nothing having happened.

errors · string[]

Error messages

warnings · string[]

Non-fatal issues found while PARSING the manifest, chiefly keys the parser had to drop. the parser already detects these and /validate and /lint already surface them, but /apply computed them and threw them away — so anyone applying without validating first got a 201 and no hint that part of their manifest was ignored. A collection-level field_passthrough: is the case that cost a customer POC: detected, described, discarded.

rollback_performed · boolean · default: false

Whether a rollback was ATTEMPTED after a failure. this used to read as 'the namespace was returned to its prior state', which it does not mean — rollback deletes only namespaces and buckets today, so any other resource created before the failure SURVIVES. Read rollback_orphans to find out what is still there.

rollback_orphans · string[]

Resources created before the failure that rollback did NOT delete, as '/'. Non-empty means the namespace is in a PARTIAL state and a straight retry will hit AlreadyExists on these. previously these were silently skipped while rollback_performed=true claimed otherwise, which is the state that had to be unpicked by hand on the Radio-Canada POC.

dry_run · boolean · default: false

Whether this was a dry run (no changes made)

task_id · string | null

The apply's task: GET /v1/tasks/{task_id} returns every resource of the plan with its states in order (planned, creating, created, exists, updated or failed with the finding; for a collection, warming or ready), each with the time it was reached. Absent on a dry run

readiness · CollectionReadiness · object[]

For each collection the manifest declares whose extractor needs Ray Serve applications for real-time inference: whether each one is served, read once from the live Serve list after apply. realtime_available true means every app is RUNNING. An app scaled to zero replicas is still RUNNING; its first call answers 503 with Retry-After (code model_warming) while it warms, so retry after that many seconds. Empty for collections whose extractor needs no Serve app.

Show child attributes

seed_batches · SeedBatchStatus · object[]

With wait_for_seed or run_acceptance: each seed: batch and where it stood when apply stopped waiting. A batch that failed or did not finish in time also appears in errors. success still reports resource creation only

Show child attributes

acceptance · AcceptanceResult · object | null

With run_acceptance: the outcome of each acceptance: step. acceptance.passed false means the namespace exists but its use case did not prove out; success still reports resource creation only, and a failed run is also named in errors

Show child attributes

next_steps · ApplyNextStep · object[]

On a successful real apply: for each retriever the manifest declares, its execute URL, a curl that queries it and its Studio page. Empty on a dry run, a failed apply, or a manifest with no retrievers

Show child attributes