API Documentation

Credits and ratings

• GET /v1/ingredients/{name} charges 1 credit on a successful 200 response. 404 (unknown ingredient) does not charge.
• POST /v1/analyze charges 1 credit per matched ingredient (each row with found: true).
• Successful JSON responses include credits_remaining in the body and the X-Credits-Remaining response header.
• comedogenicity and irritancy are integers 0–5 (0 = best, 5 = highest concern) when present.
• severity values are safe, low_risk, moderate_risk, or high_risk.

Authentication

All API requests require an API key. Include your key in the Authorization header of each request.

Authorization: Bearer YOUR_API_KEY

Base URL, schema, and SDKs

Production API host: https://api.dermalytics.dev. Swagger UI (/docs) provides interactive "Try it out" requests against the live API (use your Bearer token). The live contract is OpenAPI 3.0—use it for codegen, validation, or Postman/Insomnia imports.

Official client libraries (alpha; see each package for API surface):

• JavaScript / TypeScript: npm install dermalytics
• Python: pip install dermalytics

Get Ingredient Details

Look up a single ingredient by INCI-style name or known synonym. Successful responses include profile fields (description, comedogenicity, irritancy, identifiers, functions), a nullable category string, synonyms, and credits_remaining (see OpenAPI IngredientResponse).

import { Dermalytics } from "dermalytics";

const client = new Dermalytics({ apiKey: process.env.DERMALYTICS_API_KEY });
const ingredient = await client.getIngredient("niacinamide");
console.log(ingredient);

{
  "name": "Niacinamide",
  "severity": "safe",
  "description": "A form of vitamin B3 that helps improve skin barrier function and reduce inflammation.",
  "comedogenicity": 0,
  "irritancy": 1,
  "formula": "C6H6N2O",
  "molecular_weight": 122.12,
  "cas_no": "98-92-0",
  "ec_no": "202-713-4",
  "ph_eur_name": null,
  "functions": ["skin conditioning"],
  "category": "Antioxidants",
  "synonyms": ["Nicotinamide", "Vitamin B3"],
  "credits_remaining": 99
}

Analyze Product

Request body: { "ingredients": string[] } with at least one item (AnalyzeRequest). Each row is an IngredientAnalysis: the same detail fields as a single-ingredient lookup, plus found and nullable category. Credits are charged only for rows with found: true. The response is AnalyzeResponse: safety_status, ingredients, and credits_remaining.

import { Dermalytics } from "dermalytics";

const client = new Dermalytics({ apiKey: process.env.DERMALYTICS_API_KEY });
const analysis = await client.analyzeProduct([
  "Aqua",
  "Glycerin",
  "Niacinamide",
  "Salicylic Acid",
]);
console.log(analysis);

{
  "safety_status": "safe",
  "ingredients": [
    {
      "name": "Aqua",
      "found": true,
      "severity": "safe",
      "category": "Base",
      "description": "...",
      "comedogenicity": 0,
      "irritancy": 0,
      "formula": "H2O",
      "molecular_weight": 18.02,
      "cas_no": "7732-18-5",
      "ec_no": "231-791-2",
      "ph_eur_name": null,
      "functions": ["solvent"]
    },
    {
      "name": "Niacinamide",
      "found": true,
      "severity": "safe",
      "category": "Antioxidants",
      "description": "...",
      "comedogenicity": 0,
      "irritancy": 1,
      "formula": "C6H6N2O",
      "molecular_weight": 122.12,
      "cas_no": "98-92-0",
      "ec_no": "202-713-4",
      "ph_eur_name": null,
      "functions": ["skin conditioning"]
    },
    {
      "name": "MadeUpIngredient",
      "found": false,
      "severity": "safe",
      "category": null,
      "description": null,
      "comedogenicity": null,
      "irritancy": null,
      "formula": null,
      "molecular_weight": null,
      "cas_no": null,
      "ec_no": null,
      "ph_eur_name": null,
      "functions": []
    }
  ],
  "credits_remaining": 96
}

AI IDE Integration

Configure your AI-powered IDE (Cursor, Claude, GitHub Copilot, etc.) with best practices for using the Dermalytics API. Copy configuration files to help AI assistants understand our API patterns and conventions.

# Dermalytics API Integration Rules for Cursor

## Source of truth
- OpenAPI 3 spec: https://api.dermalytics.dev/openapi.json
- Swagger UI (interactive tests): https://api.dermalytics.dev/docs
- Base URL: https://api.dermalytics.dev
- Auth: `Authorization: Bearer <API_KEY>` on every request

## Endpoints (v1)
- GET `/v1/ingredients/{name}` — 1 credit on 200; 404 does not charge
- POST `/v1/analyze` — JSON body `{ "ingredients": string[] }`; 1 credit per row with `found: true`

## Official SDKs (alpha)
- npm: https://www.npmjs.com/package/dermalytics — `npm install dermalytics`
- PyPI: https://pypi.org/project/dermalytics/ — `pip install dermalytics`

## Responses (production JSON)
- Ingredient (`IngredientResponse`): `category` (nullable string), `synonyms[]`, `credits_remaining`, detail fields (`description`, `comedogenicity`/`irritancy` 0–5, identifiers, `functions`)
- Analyze (`AnalyzeResponse`): `safety_status`, `ingredients[]` (`IngredientAnalysis`: `found`, nullable `category`, same detail fields), `credits_remaining`
- Header `X-Credits-Remaining` mirrors body credits

## Errors
- JSON shape `{ "error": { "code", "message", "type"? } }` (see ErrorResponse in OpenAPI)
- Status: 400, 401, 402 (insufficient credits), 404 (GET unknown ingredient), 500

## Security
- Never hardcode API keys — use `DERMALYTICS_API_KEY` (or similar) from env

Best Practices