## 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 Parameters

- `namespace: string`

  The namespace to ingest data into

### Body Parameters

- `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.

    - `"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

      - `"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.

  - `ingest_as: optional "float"`

    Optional parser to apply before indexing this field.

    - `"float"`

### Returns

- `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

  - `"pending_upload"`

- `upload_url: string`

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

### Example

```http
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"
            }
          }
        }'
```

#### Response

```json
{
  "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/..."
}
```