Create Object

This endpoint creates a new object in the specified bucket. The object must conform to the bucket’s schema.

Processing: By default, objects are created in PENDING status, which means not processed yet, and are processed when a batch that includes them is submitted. An object stays PENDING until that batch run finishes with it; the batch status shows whether it has been submitted. Set the auto_process=true query parameter to automatically create a batch and submit it for processing (zero-touch workflow). Sending auto_process in the JSON body returns 422, unless the bucket schema declares a field with that name.

If the bucket has a unique_key configured, the insertion policy determines behavior:

• insert: Create only. Fail with 409 Conflict if unique key exists.
• update: Update only. Fail with 404 Not Found if unique key doesn’t exist.
• upsert: Create if new, update if exists (idempotent).

Policy resolution:

1. Use ?policy= query parameter if provided
2. Fall back to bucket’s default_policy if configured
3. Error 400 if neither is specified

POST /v1/buckets/{bucket_identifier}/objects

Create Object

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "blobs": [
    {
      "data": "https://example.com/contract-2024.pdf",
      "key_prefix": "/contract-2024/content.pdf",
      "metadata": {
        "author": "John Doe",
        "department": "Legal",
        "num_pages": 5
      },
      "property": "content",
      "type": "pdf"
    },
    {
      "data": {
        "filename": "https://example.com/images/smartphone-x1.jpg",
        "mime_type": "image/jpeg"
      },
      "key_prefix": "/contract-2024/thumbnail.jpg",
      "metadata": {
        "height": 300,
        "width": 200
      },
      "property": "thumbnail",
      "type": "image"
    }
  ],
  "category": "contracts",
  "key_prefix": "/documents",
  "title": "Service Agreement 2024",
  "year": 2024
}
'

200

{
  "blobs": [
    {
      "blob_id": "blob_1",
      "data": {
        "num_pages": 5,
        "title": "Service Agreement 2024"
      },
      "key_prefix": "/contract-2024/content.pdf",
      "metadata": {
        "author": "John Doe",
        "department": "Legal"
      },
      "property": "content",
      "type": "PDF"
    }
  ],
  "bucket_id": "bkt_9xy8z7",
  "content_hash": "28a9f5e8...",
  "created_at": "2024-10-21T10:30:00Z",
  "key_prefix": "/contract-2024",
  "metadata": {
    "category": "contracts",
    "year": 2024
  },
  "object_id": "obj_123abc456def",
  "skip_duplicates": false,
  "status": "PENDING",
  "updated_at": "2024-10-21T10:30:00Z"
}

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.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

bucket_identifier · string · required

The unique identifier of the bucket.

Query Parameters

policy · string | null

Insertion policy for unique key enforcement. Valid values: 'insert', 'update', 'upsert'. Only applies if bucket has unique_key configured. Overrides bucket's default_policy if provided.

Example:

"insert"

auto_process · boolean · default: false

Automatically create a batch and submit it for processing. When true, the object will be immediately queued for processing without requiring separate batch creation and submission calls. Ideal for onboarding and single-object workflows.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request model for creating a bucket object.

Objects can be created with blobs from two sources:

1. Direct data (URLs, base64) - Use CreateBlobRequest.data field
2. Upload references - Use CreateBlobRequest.upload_id field (from POST /buckets/{id}/uploads)

Upload Reference Workflow: For large files or client-side uploads, use the presigned URL workflow: 1. POST /buckets/{id}/uploads → Returns {upload_id, presigned_url} 2. User uploads file to presigned_url (client-side) 3. POST /uploads/{upload_id}/confirm → Validates upload 4. POST /buckets/{id}/objects with upload_id in blobs (this endpoint)

Use Cases: - Single blob with direct data (simple) - Multiple blobs from presigned uploads (recommended for large files) - Mix of direct data and upload references - Combine multiple uploads into one object

a thin subclass of shared.buckets.objects.models.CreateObjectRequest. It inherits the shared fields (key_prefix, blobs, skip_duplicates, canonicalize_source, force_remirror) and the ONE canonical normalize_blobs validator, adding only the api-surface fields below (idempotency_key, edges). Being a subclass, the field surface can only be a SUPERSET of the shared model, so a consumer reading a field one twin declares can never find the other twin omitting it.

See Also: - CreateBlobRequest for blob field documentation - POST /buckets/{id}/uploads for presigned URL generation

key_prefix · string | null

Storage key/path prefix of the object, this will be used to retrieve the object from the storage. It's at the root of the object.

Example:

"/contract-2024"

blobs · CreateBlobRequest · object[]

List of blobs to be created in this object

Show child attributes

skip_duplicates · boolean · default: false

Skip duplicate blobs, if a blob with the same hash already exists, it will be skipped.

canonicalize_source · boolean · default: true

Mirror non-S3 sources into internal S3 and reference canonically.

force_remirror · boolean · default: false

Force re-upload to S3 even if a blob with identical content already exists.

edges · EdgeModel · object[]

Typed, directed relationships from this object to other objects (customer-owned, root-level — never _internal). Populated by source adapters from companion/sidecar files, or directly on upsert. Flows to the document + MVS payload so the traverse_edge retriever stage can follow it.

Show child attributes

idempotency_key · string | null

Client-generated idempotency key for safe retries. If an object with the same idempotency_key already exists in this bucket, the existing object is returned instead of creating a duplicate. Use a UUID or deterministic hash per object.

Maximum string length: 255

Response

200

application/json

Successful Response

Response model for bucket objects.

bucket_id · string · required

ID of the bucket this object belongs to

object_id · string

Unique identifier for the object

key_prefix · string | null

Storage key/path of the object, this will be used to retrieve the object from the storage. It is similar to a file path. If not provided, it will be placed in the root of the bucket.

blobs · BlobModel · object[]

List of blobs contained in this object

Show child attributes

source_details · SourceDetails · object[]

Lineage/source details for this object; used for downstream references.

Show child attributes

edges · EdgeModel · object[]

Typed, directed relationships from this object to other objects (customer-owned, root-level — never _internal). Flows to the document + MVS payload for the traverse_edge retriever stage.

Show child attributes

status · enum<string> · default: PENDING

Processing status of the object. A new object is PENDING, which means it has not been processed yet: either no batch including it has been submitted, or it is in a submitted batch that has not finished. The status of the object's batch tells these apart. When a batch run finishes with the object it becomes COMPLETED or FAILED.

Available options: PENDING, QUEUED, IN_PROGRESS, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, INTERRUPTED, UNKNOWN, SKIPPED, DRAFT, ACTIVE, ARCHIVED, SUSPENDED, DEACTIVATED

error · string | null

The error message if the object failed to process.

Example:

"Failed to process object: Object not found"

created_at · string<date-time> | null

Timestamp when the object was created. Automatically populated by the system.

updated_at · string<date-time> | null

Timestamp when the object was last updated. Automatically populated by the system.

document_count · integer | null

Number of documents your collections have produced from this object. The object's own record in its bucket is not counted, so the value stays 0 until a collection has processed the object. Populated on GET and list responses. Null when the count cannot be read in time or the store did not answer in full. Use this to check if an object has already been processed.

consistency · WriteConsistency · object | null

When and how this object becomes a searchable document. Set on write (create) responses: managed ingestion is visible only after a collection batch processes the object — poll until document_count > 0.

Show child attributes