v29

latestOpenAPI 3.1.0raw.githubusercontent.com2026-03-233765161.7 KB

v1 data

Get a signed upload URL for large file ingest

Step 1 of 2 — Obtain a time-limited signed URL for uploading a file directly to cloud storage (GCS).

Use this instead of `/ingest` when the payload is large (e.g. > 32 MB)
to avoid sending the entire file through the API server.

**Flow:**
1. Call this endpoint → receive `upload_url`, `job_id`, `object_key`
2. HTTP **PUT** the raw file bytes to `upload_url`
3. Call `/ingest/confirm-upload` with the `job_id` and `object_key`
   to kick off the processing pipeline

The signed URL expires after the time indicated by `expires_in` (default 1 hour).

post/v1/data/ingest/upload-url

Request body

user_idstring required

User ID (always required)

persona_idstring nullable

Optional persona ID. If provided, data is ingested to this persona

project_idstring nullable

Optional project ID. If provided, data is ingested to this project

content_typestring nullable

Content category: 'text', 'image', 'video', 'pdf', 'audio', 'messages', 'file'. If omitted, the category is auto-detected after the file is uploaded.

content_descriptionstring nullable

Optional description of the content being ingested

session_idstring nullable

Session ID for grouping related ingested content

timestampstring nullable

ISO-8601 timestamp to preserve original data moment

filenamestring nullable

Filename of the file to upload

callback_urlstring nullable

Optional URL the server will POST to when the job reaches a terminal state.

notification_emailstring email nullable

Optional email address to notify when the job reaches a terminal state.

Response

Successful Response

upload_urlstring required

Signed URL for uploading the file via HTTP PUT

job_idstring required

Job ID to use when confirming the upload

object_keystring required

GCS object key where the file will live

expires_ininteger required

Seconds until the upload URL expires

successboolean

Whether the URL was generated