Objects¶

An object is a single file or asset within a dataset. Objects are the atomic unit of content in IPTO -- every document, image, audio file, or video you upload becomes an object.

What is an object?¶

When you add a file to a dataset, IPTO creates an object record that tracks the file's metadata, processing status, and review state. The original file is stored as an immutable blob, and the platform derives searchable content from it through a processing pipeline.

Each object belongs to exactly one dataset and one tenant.

Upload flow¶

Uploading an object to IPTO is a three-step process designed for reliability and security. The API never receives your file directly -- instead, you upload to a short-lived presigned URL.

Step 1: Initiate the upload¶

Send a request to the API with the file metadata (filename, MIME type, size, and checksum). The API returns an object_id and a presigned upload_url.

Step 2: Upload the file¶

Use the presigned URL to upload the file directly to storage. This keeps large files off the API server and allows resumable transfers.

Step 3: Confirm the upload¶

Once the upload completes, notify the API to confirm. The object is recorded with a review state of staged and awaits review before any further processing.

sequenceDiagram
    participant Client
    participant API
    participant Storage

    Client->>API: POST /v1/uploads (file metadata)
    API-->>Client: {object_id, upload_url}
    Client->>Storage: PUT file to upload_url
    Storage-->>Client: 200 OK
    Client->>API: POST /v1/uploads/{upload_id}/complete
    API-->>Client: {object_id, review_state: "staged"}

Object review lifecycle¶

All newly uploaded objects begin in the staged review state. Before an object can be processed and indexed, it must pass through a review step.

stateDiagram-v2
    [*] --> staged
    staged --> under_review
    under_review --> approved : Approved (proceeds to processing)
    under_review --> rejected : Rejected
    staged --> expired : After 72 hours

Presigned URLs¶

IPTO uses presigned URLs for both uploading and downloading files. A presigned URL is a time-limited, pre-authorized URL that grants temporary access to a specific storage operation without exposing long-lived credentials.

Upload URLs are generated when you initiate an upload. They authorize a PUT operation to store the file.

Download URLs are generated when a buyer requests access to an original asset after a retrieval event. They authorize a GET operation to fetch the file.

Object fields reference¶

The table below summarizes the key fields on an object resource.

FAQ¶