Merran documentation API & integrations
Share something to Merran
const url = 'http://localhost:3000/api/share';const form = new FormData();form.append('title', 'example');form.append('text', 'example');form.append('url', 'example');form.append('file', 'file');
const options = { method: 'POST', headers: {cookie: 'merran.session_token=<merran.session_token>'}};
options.body = form;
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:3000/api/share \ --header 'Content-Type: multipart/form-data' \ --cookie merran.session_token=<merran.session_token> \ --form title=example \ --form text=example \ --form url=example \ --form file=@fileWhat Android’s share sheet and the iPhone Shortcut send. A link to a recipe, as text, a form, JSON, or a file with the link in it (a text file, a .webloc, or the web page itself), is added as a recipe; several links start an import in the background. Without a link, photos, a PDF or text are read by AI: a receipt waits to be looked over for the pantry (GET /pantry/receipts/{receiptId}), and a recipe (up to 4 photos, as one) is added, when the household has AI for receipts and importing. It answers with what happened, in words a Shortcut can show, rather than an error when the link couldn’t be added. With an API key, it needs the imports: write permission.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
What was shared, as a file: a text file with the link, a .webloc, the web page, or a photo of a recipe. Several photos come as several file fields.
object
Example
{ "title": "Lemon Chicken", "text": "Making this tonight! https://example.com/lemon-chicken"}Responses
Section titled “Responses”Already there, or not added.
object
Added; already in the library (this is that recipe); several links, now importing in the background; a receipt, read and waiting for a look before it goes in the pantry; or not added.
Why it wasn’t added, for programs: “no_recipe”, “no_recipe_data”, “ai_noKey” and the like.
What happened, in words to show, as a Shortcut does.
object
A receipt: the one to look over, at /pantry/receipts/{receiptId}.
Several links: the import, to follow at /recipes/import/links/{importId}.
The recipe’s page, or the import’s.
Example
{ "outcome": "added", "code": null, "message": "Added Lemon Chicken to Merran.", "recipe": { "id": "0199e8b0-5a10-7a01-8b00-000000000006", "slug": "lemon-chicken", "name": "Lemon Chicken" }, "importId": null, "receiptId": null, "url": "https://merran.example.com/recipes/lemon-chicken"}Added.
object
Added; already in the library (this is that recipe); several links, now importing in the background; a receipt, read and waiting for a look before it goes in the pantry; or not added.
Why it wasn’t added, for programs: “no_recipe”, “no_recipe_data”, “ai_noKey” and the like.
What happened, in words to show, as a Shortcut does.
object
A receipt: the one to look over, at /pantry/receipts/{receiptId}.
Several links: the import, to follow at /recipes/import/links/{importId}.
The recipe’s page, or the import’s.
Example
{ "outcome": "added", "code": null, "message": "Added Lemon Chicken to Merran.", "recipe": { "id": "0199e8b0-5a10-7a01-8b00-000000000006", "slug": "lemon-chicken", "name": "Lemon Chicken" }, "importId": null, "receiptId": null, "url": "https://merran.example.com/recipes/lemon-chicken"}Several links, importing.
object
Added; already in the library (this is that recipe); several links, now importing in the background; a receipt, read and waiting for a look before it goes in the pantry; or not added.
Why it wasn’t added, for programs: “no_recipe”, “no_recipe_data”, “ai_noKey” and the like.
What happened, in words to show, as a Shortcut does.
object
A receipt: the one to look over, at /pantry/receipts/{receiptId}.
Several links: the import, to follow at /recipes/import/links/{importId}.
The recipe’s page, or the import’s.
Example
{ "outcome": "added", "code": null, "message": "Added Lemon Chicken to Merran.", "recipe": { "id": "0199e8b0-5a10-7a01-8b00-000000000006", "slug": "lemon-chicken", "name": "Lemon Chicken" }, "importId": null, "receiptId": null, "url": "https://merran.example.com/recipes/lemon-chicken"}Not signed in.
object
object
object
Example
{ "error": { "code": "not_found", "message": "There's nothing here.", "fields": { "name": "Give it a name." } }}Not allowed.
object
object
object
Example
{ "error": { "code": "not_found", "message": "There's nothing here.", "fields": { "name": "Give it a name." } }}Too big to share.
object
object
object
Example
{ "error": { "code": "not_found", "message": "There's nothing here.", "fields": { "name": "Give it a name." } }}© 2026 Kyle Johnson. Documentation: CC BY 4.0. Merran: AGPL-3.0-or-later.