---
title: "Submit data for an unlisted ingredient (the REST form of the submit_ingredient tool; never a formula run)"
method: POST
path: "/ingredients/submit"
---

# Submit data for an unlisted ingredient (the REST form of the submit_ingredient tool; never a formula run)

`POST /ingredients/submit`

## Request

- Base URL: `https://api.nanobaselabs.com`
- URL: `https://api.nanobaselabs.com/ingredients/submit`
- Auth: API key in header `x-nb-key`

Stores an unlisted ingredient's props and supplier documents for the ingredient library. Stored without the formula, with a one-way pseudonymous account identifier; the document text is kept privately and never returned; links are never fetched. Each submission is used right away for your own account and added to the shared library after review by Pensive Beauty® Nanoscience Labs; properties less strict than a reviewed library entry are held for review. Up to 1 MB of new document text a day and 20 MB in total per account; over that the props are still recorded and the result says the text was not stored.

## Request body

- object
  - `n` string: INCI name (inci or name accepted)
  - `props` Props: Properties of an ingredient the library does not list, researched by the caller's AI. The line is then assessed like a library ingredient of that class and echoed under declared_by_caller. Library entries win unless override is true. Invalid props return 400 invalid_props with the field.
    - `class` 'oil' | 'water_soluble' | 'peptide' | 'lipopeptide' | 'charged' | 'polymer' | 'surfactant' | 'preservative' | 'humectant' | 'neutral', required
    - `charge` 'nonionic' | 'zwitterionic' | 'cationic' | 'anionic'
    - `oil_type` 'insoluble_heavy' | 'light_ester_ripening_prone' | 'polar'
    - `mw_class` 'low' | 'medium' | 'high'
    - `mw` number
    - `valence` integer
    - `ionized_fraction` number
    - `form` 'nonionic' | 'salt' | 'acid'
    - `override` boolean
  - `source` union
    - Source: A supplier document that confirms an ingredient's information. Ask your user to upload it and send its text. Stored, never fetched; the text is kept privately and never returned or shown to other users; responses echo doc_type and doc_date only. A submission is used right away for your own account and added to the shared library after review by Pensive Beauty® Nanoscience Labs; a document whose text (doc_type plus at least about 200 characters) names the ingredient supports the review (a url alone does not count). Invalid sources return 400 invalid_source with the field.
      - `doc_type` 'TDS' | 'SDS' | 'CoA' | 'spec', required
      - `supplier` string
      - `doc_date` string: YYYY, YYYY-MM or YYYY-MM-DD
      - `url` string: http(s); never fetched
      - `excerpt` string: accepted as the same field as text
      - `text` string: the document text, up to 200 KB (204,800 bytes UTF-8)
    - Source[]
      - `doc_type` 'TDS' | 'SDS' | 'CoA' | 'spec', required
      - `supplier` string
      - `doc_date` string: YYYY, YYYY-MM or YYYY-MM-DD
      - `url` string: http(s); never fetched
      - `excerpt` string: accepted as the same field as text
      - `text` string: the document text, up to 200 KB (204,800 bytes UTF-8)
  - `ingredients` object[]
    - `n` string, required
    - `props` Props, required: Properties of an ingredient the library does not list, researched by the caller's AI. The line is then assessed like a library ingredient of that class and echoed under declared_by_caller. Library entries win unless override is true. Invalid props return 400 invalid_props with the field.
      - `class` 'oil' | 'water_soluble' | 'peptide' | 'lipopeptide' | 'charged' | 'polymer' | 'surfactant' | 'preservative' | 'humectant' | 'neutral', required
      - `charge` 'nonionic' | 'zwitterionic' | 'cationic' | 'anionic'
      - `oil_type` 'insoluble_heavy' | 'light_ester_ripening_prone' | 'polar'
      - `mw_class` 'low' | 'medium' | 'high'
      - `mw` number
      - `valence` integer
      - `ionized_fraction` number
      - `form` 'nonionic' | 'salt' | 'acid'
      - `override` boolean
    - `source` union
      - Source: A supplier document that confirms an ingredient's information. Ask your user to upload it and send its text. Stored, never fetched; the text is kept privately and never returned or shown to other users; responses echo doc_type and doc_date only. A submission is used right away for your own account and added to the shared library after review by Pensive Beauty® Nanoscience Labs; a document whose text (doc_type plus at least about 200 characters) names the ingredient supports the review (a url alone does not count). Invalid sources return 400 invalid_source with the field.
        - `doc_type` 'TDS' | 'SDS' | 'CoA' | 'spec', required
        - `supplier` string
        - `doc_date` string: YYYY, YYYY-MM or YYYY-MM-DD
        - `url` string: http(s); never fetched
        - `excerpt` string: accepted as the same field as text
        - `text` string: the document text, up to 200 KB (204,800 bytes UTF-8)
      - Source[]
        - `doc_type` 'TDS' | 'SDS' | 'CoA' | 'spec', required
        - `supplier` string
        - `doc_date` string: YYYY, YYYY-MM or YYYY-MM-DD
        - `url` string: http(s); never fetched
        - `excerpt` string: accepted as the same field as text
        - `text` string: the document text, up to 200 KB (204,800 bytes UTF-8)

## Response `200`

{ok, counted: false, results: [{n, inci, stored, status (candidate | community | rejected), document_backed, documents [{doc_type, doc_date, text_stored, document_backed}], reason, note, text_not_stored, documents_not_stored}], next, retention}

- object
  - `api_version` string

## Other responses

- `400`: invalid_input, invalid_props {field, detail, props_schema} or invalid_source {field, detail, source_schema}
- `401`: missing or invalid key
- `403`: api_key_required, or protected_ip
- `429`: rate limited
- `500`: error (see Error)

---

[API](https://skmtc.dev/nanobaselabs/apis/nanobase-api.md) · [All operations](https://skmtc.dev/nanobaselabs/apis/nanobase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nanobaselabs/apis/nanobase-api/revisions/f9c58488c2fb?raw)