Sign in
Bucket Objects

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 DRAFT status and require
batch submission for processing. Set `auto_process=true` to automatically
create a batch and submit it for processing (zero-touch workflow).

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

Path parameters

bucket_identifierstring required

The unique identifier of the bucket.

The unique identifier of the bucket.

Query parameters

policystring nullable

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

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.

auto_processboolean

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.

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.

Request body

key_prefixstring nullable

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.

skip_duplicatesboolean

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

canonicalize_sourceboolean

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

force_remirrorboolean

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

idempotency_keystring nullable

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.

Example request

{
  "blobs": [
    {
      "data": {
        "num_pages": 5,
        "title": "Service Agreement 2024"
      },
      "key_prefix": "/contract-2024/content.pdf",
      "metadata": {
        "author": "John Doe",
        "department": "Legal"
      },
      "property": "content",
      "type": "json"
    },
    {
      "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
}

Response

Successful Response

object_idstring

Unique identifier for the object

bucket_idstring required

ID of the bucket this object belongs to

key_prefixstring nullable

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.

status'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED' | 'DEACTIVATED'

Enumeration of task statuses for tracking asynchronous operations.

Task statuses indicate the current state of asynchronous operations like batch processing, object ingestion, clustering, and taxonomy execution.

Status Categories: Operation Statuses: Track progress of async operations Lifecycle Statuses: Track entity state (buckets, collections, namespaces)

Values: PENDING: Task is queued but has not started processing yet IN_PROGRESS: Task is currently being executed PROCESSING: Task is actively processing data (similar to IN_PROGRESS) COMPLETED: Task finished successfully with no errors COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) FAILED: Task encountered an error and could not complete CANCELED: Task was manually canceled by a user or system UNKNOWN: Task status could not be determined SKIPPED: Task was intentionally skipped DRAFT: Task is in draft state and not yet submitted

ACTIVE: Entity is active and operational (for buckets, collections, etc.)
ARCHIVED: Entity has been archived
SUSPENDED: Entity has been temporarily suspended

Terminal Statuses: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state.

Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately.

Polling Guidance: - Poll tasks in PENDING, QUEUED, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling

errorstring nullable

The error message if the object failed to process.

created_atstring date-time nullable

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

updated_atstring date-time nullable

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

document_countinteger nullable

Number of documents produced from this object across all collections. Populated on GET requests. Null on list responses (expensive query). Use this to check if an object has already been processed.

Example response

{
  "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": "DRAFT",
  "updated_at": "2024-10-21T10:30:00Z"
}

Changes

Changed in 4 of the 31 revisions of this API.22

  • b40f559d564a1See the full diff
    • ○

      added the new optional request property blobs/items/checksum

      new-optional-request-property

  • 1c7f318214241See the full diff
    • ●

      added the new signals enum value to the source_details/items/type response property for the response status 200

      response-property-enum-value-added

  • 5d4c905106b41See the full diff
    • ○

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API

      api-security-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9603dfdab4631See the full diff
    • ●

      added the new DEACTIVATED enum value to the status response property for the response status 200

      response-property-enum-value-added