> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.morphiaone.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.morphiaone.ai/_mcp/server. # Create a catalogue Variant POST https://api.morphiaone.ai/v1/catalogue/variants Content-Type: application/json Creates an `unpublished` variant in your catalogue with revision 1 as a `draft`: a `display_color` and one or more application definitions, each an `application_id` of yours (`lips`, `cheeks`), a custom makeup category and that category's options. The revision is compiled when it is written: every definition resolves under the category's current profile, the revision records each option's effective value and the profile `(id, version, digest)` it pinned, and a definition that does not compile is `400 INVALID_REQUEST` naming its field. A variant carries no renderer field. `external_ref` is your SKU: optional, fixed once written, and unique among your variants that are not retired (`409 EXTERNAL_REF_TAKEN`). Nothing renders a variant until a revision is approved and published. Send an `Idempotency-Key`: a retry with the same key and the same request answers the first response, byte for byte, with `Idempotency-Replayed: true`, so a response you did not receive is safe to retry. Requires the `catalogue.write` scope, which your account operator provisions; no other catalogue scope implies it. Served only where the catalogue is enabled for your environment. Reference: https://docs.morphiaone.ai/api-reference/endpoints/catalogue/variants-create ## Authentication - `X-API-Key` header (required) โ€” API key for one environment of your account. Keep server-side; never expose in browser clients. ## Request ### Headers - `Idempotency-Key` (string, optional, nullable) ### Body (application/json) This endpoint expects an object. - `applications` (list of V1CatalogueVariantsPostRequestBodyContentApplicationJsonSchemaApplicationsItems, required) - `display_color` (string, required) - `appearance` (V1CatalogueVariantsPostRequestBodyContentApplicationJsonSchemaAppearance, optional, nullable) โ€” How a shade presents (Foundation V1 D4). ``display_color`` left out is the revision's, and when sent must be. Who says each field is never sent: the server records a partner write's fields as ``source: partner`` (D20). - `default_application_id` (string, optional, nullable) - `external_ref` (string, optional, nullable) - `gtin` (string, optional, nullable) ## Response ### 201 The variant, unpublished, with revision 1 a draft - `active_revision` (integer, required, nullable) - `availability` (enum, required) - Allowed values: `unpublished`, `active`, `retired` - `created_at` (datetime, required) - `external_ref` (string, required, nullable) - `generation` (integer, required) - `gtin` (string, required, nullable) - `id` (string, required) - `kind` (enum, required) - Allowed values: `makeup`, `hair` - `latest_revision` (integer, required) - `updated_at` (datetime, required) ## Errors ### 400 Bad Request Error Invalid variant or Idempotency-Key - `error` (ErrorDetail, required) ### 401 Unauthorized Error Missing or invalid API key - `error` (ErrorDetail, required) ### 403 Forbidden Error API key lacks the catalogue.write scope - `error` (ErrorDetail, required) ### 409 Conflict Error external_ref already used, or idempotency conflict - `error` (ErrorDetail, required) ### 503 Service Unavailable Error Catalogue unavailable - `error` (ErrorDetail, required) ## Types ### V1CatalogueVariantsPostRequestBodyContentApplicationJsonSchemaApplicationsItems One application definition a revision declares: an id, a category, the colour it renders with and its custom options. ``render_color`` left out renders with the revision's ``display_color``; either way the revision stores the colour it took (program ยง4.5). The options are :class:`ApplicationDefinitionFields`'. On a ``hair_color`` definition ``render_color`` is the light stop of the hair palette and ``dark_color`` its dark stop; a dark stop left out is derived from the light one, so one colour is enough. The revision answers it as ``components.dark.color.value``. ``dark_color`` on any other category is refused. - `application_id` (string, required) - `category` (string, required) - `blend` (string, optional, nullable) - `components` (map from string to map from string to V1CatalogueVariantsPostRequestBodyContentApplicationJsonSchemaApplicationsItemsComponents, optional, nullable) - `dark_color` (string, optional, nullable) - `design` (string, optional, nullable) - `finish` (string, optional, nullable) - `intensity` (string, optional, nullable) - `placement` (string, optional, nullable) - `render_color` (string, optional, nullable) - `style` (string, optional, nullable) ### V1CatalogueVariantsPostRequestBodyContentApplicationJsonSchemaAppearance How a shade presents (Foundation V1 D4). ``display_color`` left out is the revision's, and when sent must be. Who says each field is never sent: the server records a partner write's fields as ``source: partner`` (D20). - `brand` (string, optional, nullable) - `display_color` (string, optional, nullable) - `material` (V1CatalogueVariantsPostRequestBodyContentApplicationJsonSchemaAppearanceMaterial, optional, nullable) โ€” What the shade is made of. ``finish`` left out is not asserted. - `product_name` (string, optional, nullable) - `shade_name` (string, optional, nullable) ### ErrorDetail - `code` (string, required) - `message` (string, required) - `request_id` (string, required) - `details` (ErrorDetailDetails, optional) - `doc_url` (string, optional, nullable) - `retryable` (boolean, optional, nullable) ### V1CatalogueVariantsPostRequestBodyContentApplicationJsonSchemaApplicationsItemsComponents Where one design role field's colour comes from (Foundation V1 D5): exactly one of ``ref``, an appearance path (``appearance.display_color``), or ``value``, a colour the partner states. - `ref` (string, optional, nullable) - `value` (string, optional, nullable) ### V1CatalogueVariantsPostRequestBodyContentApplicationJsonSchemaAppearanceMaterial What the shade is made of. ``finish`` left out is not asserted. - `finish` (string, optional, nullable) ### ErrorDetailDetails - map from string to any - list of map from string to any ## Examples **Request** ```json { "applications": [ { "application_id": "string", "category": "string" } ], "display_color": "string" } ``` **Response** ```json { "active_revision": 2, "availability": "active", "created_at": "2026-10-04T09:13:58.004000Z", "external_ref": "ROSE-204", "generation": 3, "gtin": "5012345678900", "id": "var_1kz8m3q5r7t9v1x3z5b7d9f1h3", "kind": "makeup", "latest_revision": 2, "updated_at": "2026-10-06T14:02:11.518000Z" } ``` **SDK Code** ```python Catalogue_variantsCreate_example import requests url = "https://api.morphiaone.ai/v1/catalogue/variants" payload = { "applications": [ { "application_id": "string", "category": "string" } ], "display_color": "string" } headers = { "X-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Catalogue_variantsCreate_example const url = 'https://api.morphiaone.ai/v1/catalogue/variants'; const options = { method: 'POST', headers: {'X-API-Key': '', 'Content-Type': 'application/json'}, body: '{"applications":[{"application_id":"string","category":"string"}],"display_color":"string"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Catalogue_variantsCreate_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.morphiaone.ai/v1/catalogue/variants" payload := strings.NewReader("{\n \"applications\": [\n {\n \"application_id\": \"string\",\n \"category\": \"string\"\n }\n ],\n \"display_color\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Catalogue_variantsCreate_example require 'uri' require 'net/http' url = URI("https://api.morphiaone.ai/v1/catalogue/variants") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"applications\": [\n {\n \"application_id\": \"string\",\n \"category\": \"string\"\n }\n ],\n \"display_color\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java Catalogue_variantsCreate_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.morphiaone.ai/v1/catalogue/variants") .header("X-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"applications\": [\n {\n \"application_id\": \"string\",\n \"category\": \"string\"\n }\n ],\n \"display_color\": \"string\"\n}") .asString(); ``` ```php Catalogue_variantsCreate_example request('POST', 'https://api.morphiaone.ai/v1/catalogue/variants', [ 'body' => '{ "applications": [ { "application_id": "string", "category": "string" } ], "display_color": "string" }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp Catalogue_variantsCreate_example using RestSharp; var client = new RestClient("https://api.morphiaone.ai/v1/catalogue/variants"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"applications\": [\n {\n \"application_id\": \"string\",\n \"category\": \"string\"\n }\n ],\n \"display_color\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Catalogue_variantsCreate_example import Foundation let headers = [ "X-API-Key": "", "Content-Type": "application/json" ] let parameters = [ "applications": [ [ "application_id": "string", "category": "string" ] ], "display_color": "string" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.morphiaone.ai/v1/catalogue/variants")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```