---
title: "Start an archive import (zip or URL list)"
method: POST
path: "/v1/imports"
tags: ["Imports"]
---

# Start an archive import (zip or URL list)

`POST /v1/imports`

## Request

- Base URL: `https://api.memestack.ai`
- URL: `https://api.memestack.ai/v1/imports`
- Auth: HTTP bearer

Creator/admin only (fresh DB role, re-checked server-side — not the JWT claim). Async bulk ingestion of up to 10,000 images per job; every image still flows through the normal per-image moderation pipeline (dedup, Gemini risk scan, determineImageStatus). Only one active import per creator at a time (409 IMPORT_ALREADY_ACTIVE). `kind: 'zip'` opens an R2 multipart upload session for the client to stream 90 MB parts into via PUT /v1/imports/{id}/parts/{n}, then POST .../complete-transfer. `kind: 'url_list'` submits the URLs synchronously (each syntactically https-only and SSRF-validated) and enqueues processing immediately.

## Request body

- object
  - `kind` 'zip' | 'url_list', required
  - `size_bytes` integer: zip only. Declared archive size; re-validated against the actual assembled object at complete-transfer time. Max 10 GiB.
  - `urls` string[]: url_list only. Each must be https and pass SSRF validation.
  - `user_context` string: Optional archive-wide tagging hint passed to the LLM tagger for every image in this import. Same 200-char semantics as the per-file upload hint.

## Response `201`

Import created. zip: multipart upload session opened. url_list: manifest written and processing already enqueued.

- object
  - `import_id` string, uuid
  - `upload_id` string: zip only — R2 multipart upload id, required on every part PUT.
  - `part_size` integer: zip only — fixed byte size every non-final part must equal exactly (IMPORT_PART_SIZE, 90 MB).

## Other responses

- `400`: Validation error (bad kind, size_bytes over the limit, urls empty/over 10,000/non-https/SSRF-blocked).
- `403`: Caller is not a creator or admin (fresh DB role).
- `409`: The caller already has an active import.

---

[API](https://skmtc.dev/memestack/apis/memestack-api.md) · [All operations](https://skmtc.dev/memestack/apis/memestack-api/llms.txt) · [OpenAPI document](https://skmtc.dev/memestack/apis/memestack-api/revisions/9d3a19565f75?raw)