API Documentation

Ingredient safety and analysis over HTTPS. Try requests in the hosted Swagger UI, use the machine-readable OpenAPI document, or connect AI agents to MCP.

Product and ingredient search

Try ingredient and product search without a key, or use your Bearer API key for full access. Use REST, the JavaScript or Python SDK, the dashboard, or MCP with an API key.

GET /v1/ingredients?q=niacinamide — search names, synonyms and exact CAS/EC identifiers.
GET /v1/products?q=cream&ingredient=Niacinamide — search available products with optional brand and ingredient filters.
GET /v1/products/{id} — retrieve a stored ingredient list by product ID.

With an API key, search uses limit (1–50) and offset (0–10,000), returning pagination.next_offset. One credit is charged per non-empty page or successful product lookup. Empty pages and missing products are not charged. Product endpoints return 503 CATALOG_UNAVAILABLE when catalog access is not enabled.

Published SDKs 1.0.0 include searchIngredients, searchProducts and getProduct in JavaScript, and search_ingredients, search_products and get_product in Python. Both support requests without an API key and return only documented fields.

Product results contain id, name, brand, category, area, ingredients_count, traits_cache and key_ingredient_tags. Lookup adds ingredient IDs, names and positions. Only active products are returned. Stored tags are not independently verified safety claims.

curl 'https://api.dermalytics.dev/v1/products?q=cream&limit=10'   -H 'Authorization: Bearer YOUR_API_KEY'

# MCP equivalents:
# search_products({"q": "cream", "limit": 10})
# get_product({"id": "PRODUCT_UUID"})

Product search workflow and availability

Comprehensive Docs

Detailed guides for every endpoint

Code Examples

Ready-to-use snippets in multiple languages

Quick Start

JSON search, lookup and analysis endpoints; try REST without a key

MCP Tools

Use the same data from AI agents

Credits and ratings

Credit charges below apply when using an API key. Requests without a key use the separate free-request allowance.

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.

Try without an API key

Make up to 5 REST requests per IP address in a 24-hour window starting with your first request. Search returns up to 3 results without pagination; analysis accepts up to 5 ingredient names. The allowance is shared across all REST data endpoints.

Try REST without a key

curl "https://api.dermalytics.dev/v1/ingredients?q=niacinamide"

Responses include X-Free-Requests-Remaining and X-Free-Requests-Reset (Unix seconds). After your second request, X-API-Key-URL links to registration. Once the allowance is used, HTTP 429 includes that link and Retry-After. Register in the dashboard for an API key and 100 welcome credits.

Requests admitted to the free allowance count even when they return no matches or a validation error. Shared networks share the allowance; IPv6 uses a /64 network. Without a key, credits_remaining: 0 is not your free-request balance. Use the response headers instead. Hosted MCP requires an API key.

Authentication

For full REST access and all hosted MCP calls, register and include your API key in the Authorization header. An invalid key returns 401; it never falls back to free access.

Authorization Header

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 (omit authorization to try it, or supply your Bearer token). The live contract is OpenAPI 3.0—use it for codegen, validation, or Postman/Insomnia imports.

Official client libraries, available as version 1.0.0:

JavaScript / TypeScript: npm install dermalytics
Python: pip install --upgrade dermalytics

Try product search and lookup without a key. The SDK examples use up to two requests from the shared five-request allowance. Node.js 18+ provides the JavaScript SDK's required global fetch; the Python SDK requires Python 3.8+.

JavaScript Example

import { Dermalytics } from "dermalytics";

const client = new Dermalytics();
const page = await client.searchProducts("cream");
if (page.data.length > 0) {
  const product = await client.getProduct(page.data[0].id);
  console.log(product.name, product.ingredients);
}
console.log(client.signupUrl);

After the second request, signupUrl (JavaScript) or signup_url (Python) contains the registration link. Exhausting the allowance raises RateLimitError. For full access, pass your API key from a server-side environment variable. See the JavaScript SDK guide or Python SDK guide for all methods, pagination and errors.

MCP for AI agents

Dermalytics exposes a hosted Model Context Protocol server at https://api.dermalytics.dev/mcp. It uses the same Bearer API key and credit rules as REST, and provides five tools: get_ingredient and analyze_product, search_ingredients, search_products and get_product.

Machine-readable MCP documentation is available at api.dermalytics.dev/v1/mcp/docs.

.cursor/mcp.jsonStreamable HTTP

{
  "mcpServers": {
    "dermalytics": {
      "url": "https://api.dermalytics.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Get Ingredient Details

GET /v1/ingredients/:name

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

JavaScript Example

import { Dermalytics } from "dermalytics";

const apiKey = process.env.DERMALYTICS_API_KEY;
if (!apiKey) throw new Error("Set DERMALYTICS_API_KEY");
const client = new Dermalytics({ apiKey });
const ingredient = await client.getIngredient("niacinamide");
console.log(ingredient);

Try It Out

GET/v1/ingredients/niacinamide

Try the live API: 5 requests per IP per 24 hours without a key. Analyze up to 5 names per request.

API key (optional)

With a key, requests use your account credits. Your key is kept only in this page's memory.

Ingredient Name

Analyze Product

POST /v1/analyze

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.

JavaScript Example

import { Dermalytics } from "dermalytics";

const apiKey = process.env.DERMALYTICS_API_KEY;
if (!apiKey) throw new Error("Set DERMALYTICS_API_KEY");
const client = new Dermalytics({ apiKey });
const analysis = await client.analyze([
  "Aqua",
  "Glycerin",
  "Niacinamide",
  "Salicylic Acid",
]);
console.log(analysis);

Try It Out

POST/v1/analyze

Try the live API: 5 requests per IP per 24 hours without a key. Analyze up to 5 names per request.

API key (optional)

With a key, requests use your account credits. Your key is kept only in this page's memory.

Ingredients (JSON array)

AI IDE Integration

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

AI IDE Configuration

Configuration files for AI-powered IDEs to help with Dermalytics API integration

.cursorrules

Cursor IDE rules for Dermalytics API integration

# 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
- MCP docs: https://api.dermalytics.dev/v1/mcp/docs
- Base URL: https://api.dermalytics.dev
- Auth: `Authorization: Bearer <API_KEY>` for full access; omit it for limited REST requests
- MCP server: https://api.dermalytics.dev/mcp with the same Bearer auth

## Try REST without an API key
- Omit Authorization for 5 requests per IP per 24-hour window starting with the first request, shared across all REST data endpoints.
- Search: up to 3 results, no pagination. Analyze: up to 5 names, each at most 100 characters.
- Admitted empty and invalid requests count. Shared networks share a quota; IPv6 uses /64.
- Read X-Free-Requests-Remaining and X-Free-Requests-Reset (Unix seconds), not credits_remaining (0 without a key).
- Starting with the second request, X-API-Key-URL links to registration. HTTP 429 includes that link and Retry-After.
- Register at https://www.dermalytics.dev/dashboard for an API key and 100 welcome credits. Send Authorization: Bearer <API_KEY> for full REST access and all hosted MCP calls.
- An invalid key returns 401; never retry without the invalid credential automatically.
- Official JavaScript/TypeScript and Python SDKs 1.0.0 are published on npm and PyPI. Both support all five REST operations and optional API keys.
- JavaScript: new Dermalytics(), searchIngredients, getIngredient, searchProducts, getProduct, analyze (alias analyzeProduct), signupUrl.
- Python: Dermalytics(), search_ingredients, get_ingredient, search_products, get_product, analyze_product, signup_url.
- SDKs return only documented fields, including nested records. Ingredient description is currently null.
- JavaScript guide: https://github.com/dermalytics-dev/dermalytics-js#readme
- Python guide: https://github.com/dermalytics-dev/dermalytics-python#readme

## Catalog
- GET /v1/ingredients?q=niacinamide: search by name, synonym or exact CAS/EC.
- GET /v1/products?q=cream: search names and brands, with optional exact brand and ingredient filters.
- GET /v1/products/{id}: retrieve a product and stored composition.
- With a key, search limit is 1–50 (default 20), offset is 0–10,000. Each non-empty page and successful product lookup costs 1 credit.
- Product summaries: id, name, brand, category, area, ingredients_count, traits_cache, key_ingredient_tags. Lookup adds ingredients (id, name, nullable position).
- Do not expose extra source, internal or removed product fields. Tags and ratings may be incomplete and are not individualized safety guarantees.
- Hosted MCP additionally exposes search_ingredients, search_products and get_product with the same authenticated contract.

## 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`

## MCP tools
- `get_ingredient({ name })` — same data as GET `/v1/ingredients/{name}`
- `analyze_product({ ingredients })` — same data as POST `/v1/analyze`

## Official SDKs
- 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), 429 (quota; read Retry-After), 503 (unavailable), 500

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

Best Practices

Error handling

• Errors return ErrorResponse: an error object with code, message, and optional type (see OpenAPI)
• 400 validation error; 401 invalid API key, or missing key for hosted MCP
• 402 insufficient credits; 404 ingredient not found on GET (no charge)
• 429 quota reached — read Retry-After and the registration link; 503 means temporarily unavailable

Security

• Never hardcode API keys - use environment variables
• Use .env files for local development
• Rotate API keys regularly
• Monitor credit balance via credits_remaining / X-Credits-Remaining

Performance

• Cache ingredient data when appropriate to reduce API calls
• Set appropriate timeouts (recommended: 10 seconds)
• Use async/await for all API operations
• Validate ingredient names before API calls

Code Quality

• Generate types from the OpenAPI spec or hand-map response shapes
• Follow consistent error handling patterns
• Pin integration tests to documented status codes and payload shapes
• Re-fetch openapi.json when deploying API upgrades; smoke-test endpoints in Swagger UI

Ready to Start Building?

Try the live playground without a key, or sign in for an API key and full access.

Disclaimer: Information provided is for educational purposes only and is not a substitute for professional medical or dermatological advice. Always consult a healthcare provider before using skincare products, especially if you have allergies or medical conditions. Learn more