{
  "openapi": "3.0.3",
  "info": {
    "title": "retraceable. Ingredient Matching API",
    "description": "Server-to-server ingredient/material name and identifier resolution.\nThis is the single place ingredient-name/identifier matching happens\nacross the product family: CheckVegan's public ingredient checker, the\nadmin dashboard, and any other internal caller all resolve terms\nthrough this one API rather than duplicating the matching logic.\n\nMatching tries, per term: exact canonical name, exact alias, and\ndetected regulatory identifiers (CAS, EC/EINECS, E-number, CI number,\nINS number). If the full term has no match, it falls back to matching\nthe text outside a trailing parenthetical, then the text inside it\n(e.g. \"Stabiliser (Acacia Gum)\"), and recurses into compound/bracketed\ningredient lists, merging all matches found.\n",
    "version": "1.0.0",
    "contact": {
      "name": "retraceable.",
      "url": "https://retraceable.io"
    },
    "license": {
      "name": "Proprietary — subject to the retraceable. API Terms of Use",
      "url": "https://retraceable.io/terms"
    }
  },
  "servers": [
    {
      "url": "https://retraceable.io",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/ingredients/search": {
      "post": {
        "operationId": "searchIngredients",
        "summary": "Resolve ingredient/material terms",
        "description": "Accepts a list of raw ingredient terms (names, aliases, or\nregulatory identifiers such as CAS/EC/E/CI/INS numbers) and\nreturns the matching ingredient(s) for each, in the same order\nas the input.\n\nA term with no match returns an empty `matches` array rather\nthan an error. A term can also resolve to more than one match\nwhen it's a compound/bracketed value that decomposes into\nseveral distinct ingredients (e.g. a flavour list naming\nmultiple E-numbers).\n",
        "tags": [
          "Ingredients"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "terms": [
                      "Carmine",
                      "E422"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolution results, one entry per input term, in input order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "results": [
                        {
                          "term": "Carmine",
                          "matches": [
                            {
                              "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                              "canonical_name": "Carmine",
                              "slug": "carmine",
                              "cas_number": "1390-65-4",
                              "ec_number": "215-680-6",
                              "e_number": "E120",
                              "ci_number": "75470",
                              "cosing_id": "34348",
                              "ins_number": "120",
                              "vegan_classification": "not_vegan",
                              "vegetarian_classification": "not_vegetarian",
                              "vegan_alternatives": [
                                {
                                  "id": "9c4e3a2b-6d1f-4e8a-8b2c-1a2b3c4d5e6f",
                                  "canonical_name": "Beet Red",
                                  "slug": "beet-red"
                                },
                                {
                                  "id": "7d2f1c8a-4b9e-4a3d-9f0e-2b3c4d5e6f7a",
                                  "canonical_name": "Lycopene",
                                  "slug": "lycopene"
                                }
                              ],
                              "matched_text": "Carmine"
                            }
                          ]
                        },
                        {
                          "term": "E422",
                          "matches": [
                            {
                              "id": "3b9e2f6a-7a1a-4b3b-9e2e-2f6a7a1a4b3b",
                              "canonical_name": "Glycerin",
                              "slug": "glycerin",
                              "cas_number": "56-81-5",
                              "ec_number": "200-289-5",
                              "e_number": "E422",
                              "ci_number": null,
                              "cosing_id": "34260",
                              "ins_number": "422",
                              "vegan_classification": "unconfirmed",
                              "vegetarian_classification": "unconfirmed",
                              "vegan_alternatives": [],
                              "matched_text": "E422"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`terms` was missing, not an array, or empty.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "error": "terms must be a non-empty array of strings"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token, or the token has been revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "error": "invalid_token"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Token's daily request limit has been exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "error": "limit_exceeded",
                      "limit": 1000
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Failure recording API token usage.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "error": "limit_exceeded"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token issued via `POST /api/api-tokens` (requires an\nauthenticated brand session). The raw token is only shown once at\ncreation; the server stores and checks a SHA-256 hash of it.\nTokens may carry a `daily_limit`; tokens without one are\nunlimited.\n"
      }
    },
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "required": [
          "terms"
        ],
        "properties": {
          "terms": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "description": "Raw ingredient/material terms to resolve — canonical names, aliases, or regulatory identifiers (CAS, EC/EINECS, E-number, CI number, INS number) in any of their commonly written forms (e.g. \"E 460(i)\", \"INS476\", \"CI 12840\").",
            "example": [
              "Carmine",
              "E422"
            ]
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TermResult"
            }
          }
        }
      },
      "TermResult": {
        "type": "object",
        "required": [
          "term",
          "matches"
        ],
        "properties": {
          "term": {
            "type": "string",
            "description": "The input term this result corresponds to, verbatim."
          },
          "matches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IngredientMatch"
            },
            "description": "Zero or more ingredient matches for this term. Empty when nothing in the database matched. More than one entry means the term was a compound/bracketed value that decomposed into several distinct ingredients."
          }
        }
      },
      "IngredientMatch": {
        "type": "object",
        "description": "An ingredient/material row from the database, plus the substring of the original term that produced this match.",
        "required": [
          "id",
          "canonical_name",
          "slug",
          "vegan_classification",
          "vegetarian_classification",
          "vegan_alternatives",
          "matched_text"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "canonical_name": {
            "type": "string",
            "description": "Canonical English name of the ingredient/material."
          },
          "slug": {
            "type": "string",
            "description": "URL slug, used for e.g. `checkvegan.org/glossary/:slug`."
          },
          "cas_number": {
            "type": "string",
            "nullable": true,
            "description": "CAS registry number, e.g. \"1390-65-4\"."
          },
          "ec_number": {
            "type": "string",
            "nullable": true,
            "description": "EC/EINECS/ELINCS number, e.g. \"215-680-6\"."
          },
          "e_number": {
            "type": "string",
            "nullable": true,
            "description": "EU food/cosmetic additive E-number, e.g. \"E120\"."
          },
          "ci_number": {
            "type": "string",
            "nullable": true,
            "description": "Colour Index number, e.g. \"75470\"."
          },
          "cosing_id": {
            "type": "string",
            "nullable": true,
            "description": "EU CosIng database identifier."
          },
          "ins_number": {
            "type": "string",
            "nullable": true,
            "description": "Codex International Numbering System food additive number, e.g. \"120\"."
          },
          "vegan_classification": {
            "type": "string",
            "enum": [
              "vegan",
              "not_vegan",
              "unconfirmed"
            ],
            "description": "Explicit, independently-set end-user-facing vegan status. Use this for display — not the internal `classification` column (not exposed by this API)."
          },
          "vegetarian_classification": {
            "type": "string",
            "enum": [
              "vegetarian",
              "not_vegetarian",
              "unconfirmed"
            ]
          },
          "vegan_alternatives": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AlternativeIngredient"
            },
            "description": "Other ingredients recorded as vegan alternatives to this one (via the `ingredient_alternatives` table), e.g. plant-derived substitutes for an animal-derived colourant. Empty when none are recorded."
          },
          "matched_text": {
            "type": "string",
            "description": "The exact substring of the original input term that produced this match. For a compound term that decomposes into several ingredients, each match is tagged with the specific part of the input it came from, rather than repeating the whole searched string for every row."
          }
        }
      },
      "AlternativeIngredient": {
        "type": "object",
        "description": "A minimal reference to a vegan-alternative ingredient/material.",
        "required": [
          "id",
          "canonical_name",
          "slug"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "canonical_name": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "description": "URL slug, used for e.g. `checkvegan.org/glossary/:slug`."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "RateLimitErrorResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorResponse"
          },
          {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer",
                "description": "The token's configured daily_limit that was exceeded."
              }
            }
          }
        ]
      }
    }
  }
}