Start an import
Creates an import job and enqueues it. Returns `201` immediately with a record whose `status` is `pending` — extraction happens asynchronously on a worker, and takes anywhere from a few seconds to a couple of minutes depending on the source. Which fields are required depends on `type`: | `type` | Required | Notes | | --- | --- | --- | | `web` | `url` | Must be `https`. Recipe sites, Instagram, YouTube, TikTok. | | `media` | `file_ids` | Upload images first with `POST /api/files`. | | `text` | `text` or `text_file_id` | `text` must be at least 3 characters. | | `image_batch` | `file_ids` | Fans out into one child import per image. | Track the job by polling `GET /api/imports/{id}` or by subscribing to `GET /api/events/stream`. When `status` becomes `completed`, `recipe_id` points at the created recipe.
Creates an import job and enqueues it. Returns 201 immediately with a
record whose status is pending — extraction happens asynchronously
on a worker, and takes anywhere from a few seconds to a couple of
minutes depending on the source.
Which fields are required depends on type:
type | Required | Notes |
|---|---|---|
web | url | Must be https. Recipe sites, Instagram, YouTube, TikTok. |
media | file_ids | Upload images first with POST /api/files. |
text | text or text_file_id | text must be at least 3 characters. |
image_batch | file_ids | Fans out into one child import per image. |
Track the job by polling GET /api/imports/{id} or by subscribing to
GET /api/events/stream. When status becomes completed, recipe_id
points at the created recipe.
Authorization
bearerAuth A Clerk session JWT. Obtain one with a Clerk frontend SDK
(session.getToken()) or, for server-to-server use, with a Clerk
machine token. The token's sub claim is the Flambe user id that scopes
every request.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/imports" \ -H "Content-Type: application/json" \ -d '{ "type": "web", "url": "https://www.seriouseats.com/best-chocolate-chip-cookies" }'{ "id": "4d1f8c2e-9a3b-4f1e-8c7d-1b2a3c4d5e6f", "user_id": "user_2abcDEF", "type": "web", "status": "pending", "url": "https://www.seriouseats.com/best-chocolate-chip-cookies", "created_at": "2026-09-10T18:22:04.512Z", "updated_at": "2026-09-10T18:22:04.512Z"}Cancel an import POST
Cancel an import that has not finished. A worker already mid-extraction observes the cancellation at its next checkpoint, so the job may run a little longer before it stops.
Get an import GET
Fetch one import. Poll this to follow a job to completion; a one- to two-second interval is plenty, and `/api/events/stream` avoids polling altogether.