Create upload URL

POST/v1/data/{namespace}/requests/upload-url

Request a pre-signed upload URL for large JSONL batches into a namespace. After receiving upload_url, upload your JSONL file using PUT {upload_url} with header Content-Type: application/json; put each JSON object on a new line.

Path ParametersExpand Collapse

namespace: string

The namespace to ingest data into

Body ParametersJSONExpand Collapse

schema: optional map[object { belongs_to, content_type, display_hint, 2 more } ]

Schema mapping field names to their definitions. Use content_type to specify which fields contain URLs that should be processed (images, videos, or websites), datetime fields, or ‘metadata’ for fields that should be stored but not indexed. Use display_hint to provide UI rendering hints.

belongs_to: optional string

The parent object namespace this field belongs to, creating a parent-child relationship with that namespace.

content_type: optional "image_url" or "video_url" or "audio_url" or 4 more

The type of content (image_url, video_url, audio_url, website_url, datetime, metadata, or card). When specified as a URL type, SafetyKit will process the URL. Use ‘metadata’ for fields that should be stored but not indexed.

One of the following:

"image_url"

"video_url"

"audio_url"

"website_url"

"datetime"

"metadata"

"card"

display_hint: optional object { name, order, type }

Display hint for UI rendering of this field

name: optional string

Display label to show for this field in the UI

order: optional number

Display ordering for this field. Use 0 to hide the field from list views.

type: optional "title" or "subtitle" or "description" or 10 more

The display hint type

One of the following:

"title"

"subtitle"

"description"

"primary_image_url"

"video_url"

"audio_url"

"location"

"date"

"compact_text"

"markdown"

"html"

"card"

"chat_thread"

field_limit: optional number

Maximum amount of this field to include when sending to AI models. For text fields, this is the character limit. For array fields (e.g. image URLs), this is the maximum number of items.

minimum0

exclusiveMinimum

ingest_as: optional "float"

Optional parser to apply before indexing this field.

ReturnsExpand Collapse

expires_at: string

ISO timestamp when upload_url expires (12 hours after issuance)

objectKey: string

S3 object key where uploaded JSONL will be processed from

requestId: string

Unique identifier for this upload request

status: "pending_upload"

Request is waiting for file upload

upload_url: string

Pre-signed upload URL for PUT-ing JSONL content (Content-Type: application/json)

Create upload URL

curl https://api.safetykit.com/v1/data/$NAMESPACE/requests/upload-url \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $SAFETYKIT_API_KEY" \
    -d '{
          "schema": {
            "title": {
              "display_hint": {
                "name": "Profile name",
                "order": 1,
                "type": "title"
              }
            },
            "description": {
              "display_hint": {
                "order": 10,
                "type": "description"
              }
            },
            "profile_image": {
              "content_type": "image_url",
              "display_hint": {
                "order": 15,
                "type": "primary_image_url"
              }
            },
            "cover_photo": {
              "content_type": "image_url"
            },
            "website": {
              "content_type": "website_url"
            },
            "promo_video": {
              "content_type": "video_url",
              "display_hint": {
                "type": "video_url"
              }
            },
            "shop_id": {
              "belongs_to": "shops"
            },
            "internal_notes": {
              "content_type": "metadata"
            }
          }
        }'

{
  "expires_at": "2026-01-15T12:30:00.000Z",
  "objectKey": "TEAM_ID/data-api-request-input/products/request_01K....jsonl",
  "requestId": "req_01h2m7qdmdjckc30e1mnq6xqfd",
  "status": "pending_upload",
  "upload_url": "https://s3.amazonaws.com/..."
}

Returns Examples

{
  "expires_at": "2026-01-15T12:30:00.000Z",
  "objectKey": "TEAM_ID/data-api-request-input/products/request_01K....jsonl",
  "requestId": "req_01h2m7qdmdjckc30e1mnq6xqfd",
  "status": "pending_upload",
  "upload_url": "https://s3.amazonaws.com/..."
}