> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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:** ```bash curl -X POST /v1/manifest/apply \ -H "Authorization: Bearer $API_KEY" \ -H "X-Namespace: ns_xxx" \ -F "manifest_file=@mixpeek.yaml" ``` **Example manifest:** ```yaml 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 } ``` ## OpenAPI ````yaml post /v1/manifest/apply openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: - BearerAuth: [] paths: /v1/manifest/apply: post: tags: - Manifest summary: Apply Manifest description: >- 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:** ```bash curl -X POST /v1/manifest/apply \ -H "Authorization: Bearer $API_KEY" \ -H "X-Namespace: ns_xxx" \ -F "manifest_file=@mixpeek.yaml" ``` **Example manifest:** ```yaml 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 } ``` operationId: apply_manifest_v1_manifest_apply_post parameters: - name: dry_run in: query required: false schema: type: boolean description: >- 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 default: false title: Dry Run description: >- 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 - name: deadline_seconds in: query required: false schema: anyOf: - type: number maximum: 1800 minimum: 1 - type: 'null' description: >- 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. title: Deadline Seconds description: >- 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. - name: wait_for_seed in: query required: false schema: type: boolean description: >- 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 default: false title: Wait For Seed description: >- 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 - name: run_acceptance in: query required: false schema: type: boolean description: >- 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 default: false title: Run Acceptance description: >- 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 - name: mode in: query required: false schema: $ref: '#/components/schemas/ApplyMode' description: >- 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. default: create_only description: >- 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. requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/Body_apply_manifest_v1_manifest_apply_post' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ApplyResult' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: ApplyMode: type: string enum: - create_only - create_missing - upsert title: ApplyMode description: Mode for applying manifests. Body_apply_manifest_v1_manifest_apply_post: properties: manifest_file: type: string contentMediaType: application/octet-stream title: Manifest File description: YAML manifest file parameters: anyOf: - type: string - type: 'null' title: Parameters description: >- 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. type: object required: - manifest_file title: Body_apply_manifest_v1_manifest_apply_post ApplyResult: properties: success: type: boolean title: Success description: Whether all resources were created successfully resources: items: $ref: '#/components/schemas/ResourceResult' type: array title: Resources description: Results for each resource created_count: type: integer title: Created Count description: Number of resources created default: 0 failed_count: type: integer title: Failed Count description: Number of resources that failed default: 0 skipped_count: type: integer title: Skipped Count description: Number of resources skipped default: 0 would_create_count: type: integer title: Would Create Count description: >- 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. default: 0 updated_count: type: integer title: Updated Count description: >- 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. default: 0 errors: items: type: string type: array title: Errors description: Error messages warnings: items: type: string type: array title: Warnings description: >- 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: type: boolean title: Rollback Performed description: >- 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. default: false rollback_orphans: items: type: string type: array title: Rollback Orphans description: >- 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: type: boolean title: Dry Run description: Whether this was a dry run (no changes made) default: false task_id: anyOf: - type: string - type: 'null' title: Task Id description: >- 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: items: $ref: '#/components/schemas/CollectionReadiness' type: array title: Readiness description: >- 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. seed_batches: items: $ref: '#/components/schemas/SeedBatchStatus' type: array title: Seed Batches description: >- 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 acceptance: anyOf: - $ref: '#/components/schemas/AcceptanceResult' - type: 'null' description: >- 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` next_steps: items: $ref: '#/components/schemas/ApplyNextStep' type: array title: Next Steps description: >- 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 type: object required: - success title: ApplyResult description: Result of applying a manifest. examples: - 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 ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false ResourceResult: properties: resource_type: type: string title: Resource Type description: Type of resource (namespace, bucket, etc.) name: type: string title: Name description: Resource name from manifest resource_id: anyOf: - type: string - type: 'null' title: Resource Id description: Created resource ID status: $ref: '#/components/schemas/ResourceResultStatus' description: >- What apply did to this resource. `created` and `skipped` are what they sound like. `would_create` appears only on a dry run, for a resource the real apply would create. `exists` means it was already what the manifest declares. `drifted` means it differs and still does. `updated` means apply patched it. `pending` means the resource exists but waits on something apply cannot do itself, named in `pending_reason`. READ `updated` WITH `refused`: a resource can be `updated` AND carry refused fields, because apply patches what the update surface accepts and reports the rest. `updated` on its own does not mean every declared field was applied, and a caller that treats it as reconciled will report a partly-applied manifest as complete. error: anyOf: - type: string - type: 'null' title: Error description: Error message if failed generated_for: anyOf: - type: string - type: 'null' title: Generated For description: >- Present when the manifest did not declare this resource itself: the name of the taxonomy whose inline labels generated it (its label bucket, collection, retriever or seed). Edit the taxonomy's labels to change it. pending_reason: anyOf: - type: string - type: 'null' title: Pending Reason description: >- Present when status is `pending`: what the resource waits for and what happens when it arrives. drift: anyOf: - items: type: string type: array - type: 'null' title: Drift description: >- Fields the manifest DECLARES that differ from the live resource. Present when status is `drifted`, and ALSO on an `updated` resource, where it is HISTORICAL: the record of what apply changed, not a difference that is still there. A caller that renders any non-empty value as 'differs' will announce the opposite of what happened on every patched row. Named rather than counted: 'collection c1 differs: schedule' is actionable, 'exists' is not. Only fields the manifest explicitly set are compared — an omitted field asserts nothing, and treating an omission as drift would make every apply drift on server-set defaults. examples: - - schedule - feature_extractor refused: anyOf: - items: type: string type: array - type: 'null' title: Refused description: >- Fields the manifest declares, and that DIFFER, which apply would not change. Present under `upsert` when the resource's own update surface does not accept a field or refuses the value. A refusal is reported per field rather than as a failed apply: the rest of the manifest still applies, and the caller learns exactly which resource and which field to take up by hand. A bucket's schema is the standing example — it is patchable through the API and a destructive change is refused, so upsert does not route around that guard. examples: - - budget_limits drift_not_compared: anyOf: - items: type: string type: array - type: 'null' title: Drift Not Compared description: >- Fields the manifest declares that could NOT be compared, because the live resource has no corresponding key. Reported rather than dropped: a field silently excluded from the comparison is indistinguishable from one that matched, and that is the exact ambiguity `drifted` exists to remove. type: object required: - resource_type - name - status title: ResourceResult description: Result of applying a single resource. examples: - name: video_search resource_id: ns_abc123 resource_type: namespace status: created CollectionReadiness: properties: collection: type: string title: Collection description: Collection name from the manifest feature_extractor: type: string title: Feature Extractor description: Registry extractor id the collection runs, e.g. text_extractor_v1 realtime_available: anyOf: - type: boolean - type: 'null' title: Realtime Available description: >- true when every Serve app below is RUNNING, false when one is absent or not RUNNING, null when the live Serve list could not be read serve_apps: items: $ref: '#/components/schemas/ServeAppStatus' type: array title: Serve Apps description: Each Ray Serve application the extractor needs, with its status type: object required: - collection - feature_extractor title: CollectionReadiness description: Whether one collection's real-time inference is served after apply. SeedBatchStatus: properties: bucket: type: string title: Bucket description: Bucket name the seed ingested into batch_id: type: string title: Batch Id description: The seed batch's id status: type: string title: Status description: >- The batch status when apply stopped waiting: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, PROCESSING and so on. UNKNOWN when the batch could not be read terminal: type: boolean title: Terminal description: true when the batch finished, whether or not it succeeded usable: type: boolean title: Usable description: >- true when the batch finished COMPLETED or COMPLETED_WITH_ERRORS, so its documents can be queried documents_written: anyOf: - type: integer - type: 'null' title: Documents Written description: Documents the batch wrote, when the batch reports it failed_objects: anyOf: - type: integer - type: 'null' title: Failed Objects description: Objects the batch could not process error: anyOf: - type: string - type: 'null' title: Error description: Why the batch could not be read x-mixpeek-redacted: driver_text type: object required: - bucket - batch_id - status - terminal - usable title: SeedBatchStatus description: Where one `seed:` batch stands, read while apply waits for it. AcceptanceResult: properties: passed: type: boolean title: Passed description: true only when every step, and the cost check, passed steps: items: $ref: '#/components/schemas/AcceptanceStepResult' type: array title: Steps description: Each step in manifest order type: object required: - passed title: AcceptanceResult description: The manifest's `acceptance:` steps, run after apply. ApplyNextStep: properties: retriever: type: string title: Retriever description: Retriever name from the manifest retriever_id: type: string title: Retriever Id description: The retriever's id namespace: anyOf: - type: string - type: 'null' title: Namespace description: Namespace name from the manifest, sent as X-Namespace execute_url: type: string title: Execute Url description: 'POST here with {"inputs": ...} to run the retriever' inputs: additionalProperties: true type: object title: Inputs description: >- Inputs for a first query: the manifest's acceptance query for this retriever when it has one, otherwise each required input of the retriever's input_schema as a to fill in inputs_proven: type: boolean title: Inputs Proven description: >- true when `inputs` is the manifest's acceptance query. It answered only if that acceptance step passed on this apply default: false curl: type: string title: Curl description: A curl that runs the query; set MIXPEEK_API_KEY first studio_url: type: string title: Studio Url description: The retriever in Studio type: object required: - retriever - retriever_id - execute_url - curl - studio_url title: ApplyNextStep description: How to query one retriever the apply created or found. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ResourceResultStatus: type: string enum: - created - skipped - failed - exists - drifted - updated - would_create - pending title: ResourceResultStatus description: Status of a resource creation attempt. ServeAppStatus: properties: name: type: string title: Name description: Ray Serve application name, as the engine deploys it. status: type: string title: Status description: >- Live status of that application on the deployment serving this request. A Ray Serve status such as 'RUNNING', 'DEPLOYING' or 'UNHEALTHY'; 'absent' when the deployment does not serve it; 'unconfigured' when it runs but the deployment lacks the model provider's key or credentials; 'unknown' when the live list could not be read. type: object required: - name - status title: ServeAppStatus description: One Ray Serve application an extractor needs, with its live status. AcceptanceStepResult: properties: name: type: string title: Name description: Step name from the manifest kind: type: string title: Kind description: >- query, documents, alert or realtime, as the manifest declares; `cost` for the max_cost_usd check that closes the run passed: type: boolean title: Passed description: >- true only when the step ran and every expected outcome held. A step that could not run (deadline reached, seed batch failed, resource missing, cost cap reached) is false, with `error` saying why expected: additionalProperties: true type: object title: Expected description: The step's `expect` fields as declared observed: anyOf: - additionalProperties: true type: object - type: 'null' title: Observed description: >- What the step measured, e.g. results and top_value for a query, documents for a collection, fires for an alert, dims for a realtime call, spent_usd for the cost check. null when it did not run error: anyOf: - type: string - type: 'null' title: Error description: Why the step failed or could not run x-mixpeek-redacted: driver_text type: object required: - name - kind - passed title: AcceptanceStepResult description: The outcome of one `acceptance:` step. securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.