BeautySpark

Search BeautySpark's makeup and colour-season guides for sections that answer a question, e.g. eyeliner for hooded eyes or how to find your undertone. Returns up to 5 sections with a short snippet and a link; read one in full with get_guide. Cite the returned url. When nothing matches, the result has a note saying no BeautySpark guide covers it.

Read one section of a BeautySpark guide in full, by an id from search_guides. Also lists the ids and headings of the other sections of the same article. Cite the returned url.

For research modes (deep research, company knowledge). In chat, use search_guides instead. Searches all public BeautySpark content: guide sections (id "<locale>/<slug>#<anchor>"), article looks (id "look:<id>") and colour-season palette pages (id "season:<season>"). Read any result with fetch.

For research modes (deep research, company knowledge). In chat, use get_guide instead. Returns the full text of one item from search: a guide section ("<locale>/<slug>#<anchor>"), an article look ("look:<id>") or a colour-season palette page ("season:<season>").

BeautySpark's palette for one of the 12 color seasons: best, neutral and avoid colors with hex codes, plus the eye makeup and lips & cheeks advice from the season guide. Cite the returned URLs.

BeautySpark's top product pick per category (blush, highlighter, eyeliner, lipstick, lip gloss, bronzer, eyeshadow palette) for a color season, each with the reason and the article it comes from.

Looks a product (and optional shade) up in BeautySpark's season picks. Returns the seasons it is recommended for, or match: null when BeautySpark has not reviewed it; then do not present any verdict as BeautySpark's. Pass season to also get that season's palette for comparison.

Find makeup looks shown in BeautySpark articles, filtered by color season, article type and words. With a season, looks made for that season come first; general looks (no season) follow and are labelled. Returns look ids for get_article_look and the article URL to cite.

Get the steps and shades of one makeup look from a BeautySpark article. The id is a look id returned by find_article_looks ("/images/blog/<article-slug>/<look-name>").

Search the user's saved looks in BeautySpark My Looks by words, tag, category, favourite or person. Returns look ids for get_my_look.

Get one saved look in full: steps, products and shades, tags, categories, notes, photos and a link to open it in BeautySpark.

Save a new look to the user's BeautySpark My Looks. Photos can't be added from chat: if the user attached or mentions a photo, tell them before saving that only the text is saved and that they can add the photo in BeautySpark from the returned link. Repeating the same save within 10 minutes returns the first look instead of a copy.

Change a saved look. Only the fields you send change; list fields (steps, products, tags, categories, occasions) replace the stored list whole. Look photos are kept. Steps can't be changed while any step has a photoUrl; the user edits those steps in the BeautySpark app. When the look's steps link products or shades, send productRefs and shadeRefs on every step you send ([] for a step with none): a step sent without them is refused unless products is sent too. To unlink every step, send products too.

Delete a saved look from the user's BeautySpark My Looks. The look is removed.

Save a finished BeautySpark generation (a jobId from list_my_generations) as a look in My Looks. Saving the same generation again returns the look already saved.

The user's BeautySpark analysis: color season, undertone, eye shape, face shape and app language. Fields are null until the selfie analysis has been run in the app.

Takes no parameters.

The palettes the user scanned in BeautySpark, with shade names and hex colors. Use them to advise with products the user owns; pass a paletteId as a product's userPaletteId in save_my_look.

Takes no parameters.

The user's finished BeautySpark look generations, newest first: title, date, thumbnail and whether it is already in My Looks. Pass a jobId to save_generation_to_my_looks to save one.

Prepare a try-on: BeautySpark recreates a makeup look on the user's selfie. Give one reference: articleLookId (from find_article_looks) or savedLookId (from search_my_looks). Photos (a reference photo or a different selfie) can only be uploaded in the try-on widget, never taken from chat attachments. The saved selfie is used unless the user uploads another in the widget. Returns the credit cost and balance without charging; nothing is generated until confirm_look_generation.

Start the try-on prepared by try_look_from_photo. This spends the BeautySpark credits it quoted. The try-on widget calls it when the user presses Confirm. If no widget is showing, ask the user to confirm the cost first and call it only after they agree. Calling it again for the same quote returns the same job without charging again. If it answers conflict, the same quote is still being confirmed: call it again in a few seconds.

Check a try-on started by confirm_look_generation. Waits up to waitSeconds (at most 25) for it to finish before answering. When completed, the result includes the image URL and, when the look has them, its step-by-step instructions with the colours for each step.

Used by the try-on widget to upload a photo the user picked. Returns an upload URL valid for 15 minutes.