Add recipes from several links

POST

/api/recipes/import/links

curl --request POST \
  --url http://localhost:3000/api/recipes/import/links \
  --header 'Content-Type: application/json' \
  --cookie merran.session_token=<merran.session_token> \
  --data '{ "urls": [ "https://example.com/garlic-rice", "https://example.com/lemon-chicken" ], "tag": "to try" }'

• Your Merran

Up to 100 links, imported one at a time in the background: follow along at /recipes/import/links/{importId}, which says how each link went. A link the library has already gives back that recipe rather than a new one. With an API key, it needs the imports: write permission.

Authorizations

• session
• apiKey

Request Body^required

Media typeapplication/json

object

urls

required

Array<string>

>= 1 items <= 100 items

tag

Added to every recipe it makes, like “to try”.

string | null

<= 40 characters

Example

{
  "urls": [
    "https://example.com/garlic-rice",
    "https://example.com/lemon-chicken"
  ],
  "tag": "to try"
}

Responses

202

Importing.

Media typeapplication/json

object

id

required

The import’s job.

string

status

required

string

Allowed values: queued running done failed cancelled

tag

required

string | null

total

required

integer

done

required

integer

added

required

integer

already

required

integer

failed

required

integer

stopped

required

integer

items

required

Array<object>

object

url

required

string

state

required

Where the link has got to: added, already in the library, failed (see error), or stopped before it was reached.

string

Allowed values: waiting adding added already failed stopped

recipe

required

The recipe it made, or was already.

object

id

required

string

slug

required

string

name

required

string

photo

required

string | null

error

required

string | null

createdAt

required

string format: date-time

finishedAt

required

string | null format: date-time

Example

{
  "id": "0199e8b0-5a10-7a01-8b00-00000000000b",
  "status": "running",
  "tag": "to try",
  "total": 2,
  "done": 1,
  "added": 1,
  "already": 0,
  "failed": 0,
  "stopped": 0,
  "items": [
    {
      "url": "https://example.com/garlic-rice",
      "state": "added",
      "recipe": {
        "id": "0199e8b0-5a10-7a01-8b00-000000000007",
        "slug": "garlic-rice",
        "name": "Garlic Rice",
        "photo": null
      },
      "error": null
    },
    {
      "url": "https://example.com/lemon-chicken",
      "state": "adding",
      "recipe": null,
      "error": null
    }
  ],
  "createdAt": "2026-10-15T18:30:00.000Z",
  "finishedAt": null
}

400

None of them is a link Merran can fetch.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

401

Not signed in.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

403

Not allowed.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}