Documentation & API — Formula AI Global

Overview

The Formula AI API gives you programmatic access to all of our platform's capabilities — from smart formula search to knowledge extraction from books and regulatory compliance checks — securely, quickly, and easily.

REST

JSON Standard

99.9%

Uptime SLA

< 200ms

Average latency

v3.0

Current version

Base API URL:

BASE https://api.jamilformula.com/v3

Authentication

All API requests require an API key sent in the header. Get your key from Dashboard → Settings → API Keys.

curl -X GET "https://api.jamilformula.com/v3/formulas/search" \
  -H "Authorization: Bearer fa_live_sk_..." \
  -H "Content-Type: application/json"
            

⚠️ Security: Never expose your key in frontend code. Always use environment variables.

Formula search

AI-powered smart search for any chemical formula using natural language.

POST /formulas/search

Parameters

Field	Type	Description
`query`	string	Product name to search for
`category`	string	Category (cosmetics, detergents, ...)
`country`	string	Country code for compliance check (ISO-2)
`language`	string	Response language (ar, en, fr, ...)

Example request

// JavaScript / Node.js
const response = await fetch('https://api.jamilformula.com/v3/formulas/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.FORMULA_AI_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'natural shampoo for dry hair',
    category: 'cosmetics',
    country: 'SA',
    language: 'en'
  })
});

const data = await response.json();
console.log(data.formulas);
            

Example response

{
  "id": "FA-2026-04891",
  "name": "Natural shampoo for dry hair",
  "category": "cosmetics",
  "confidence": 0.96,
  "components": [
    {
      "name": "Sodium Laureth Sulfate",
      "cas": "68585-34-2",
      "percentage": 14.0,
      "function": "Primary Surfactant"
    },
    // ... 8 more components
  ],
  "compliance": { "SA": true, "EU": true }
}
            

Regulatory compliance check

Verify that a formula complies with regulations in any country in the world.

POST /compliance/check

# Python
import requests

response = requests.post(
  'https://api.jamilformula.com/v3/compliance/check',
  headers={'Authorization': f'Bearer {os.environ["FORMULA_AI_KEY"]}'},
  json={
    'formula_id': 'FA-2026-04891',
    'countries': ['SA', 'AE', 'EG', 'EU', 'US']
  }
)
result = response.json()
print(f"Compliant in {result['compliant_countries']} of {result['total']} countries")
            

Extract from a book

Upload a book and extract formulas from it programmatically.

POST /books/extract

# Upload book and extract formulas
curl -X POST "https://api.jamilformula.com/v3/books/extract" \
  -H "Authorization: Bearer fa_live_sk_..." \
  -F "file=@./CosmeticFormulary.pdf" \
  -F "language=auto" \
  -F "complete_missing=true"
            

Official SDK packages

Use our official packages for better support and automatic error handling.

⚡

Node.js / TypeScript

npm install @formula-ai/sdk

🐍

Python

pip install formula-ai

🐹

Go

go get github.com/formula-ai/go

☕

Java / Kotlin

implementation 'ai.formula:sdk:3.0'

Rate limits

Limits depend on your plan:

Plan	Requests/day	Requests/minute	Max latency
Free	—	—	—
Professional	1,000	30	30s
Business	50,000	200	60s
Enterprise	Unlimited	1,000	120s

Error codes

Code	Description	Solution
`401`	Unauthenticated	Check your API key
`403`	Plan does not allow	Upgrade your plan
`429`	Rate limit exceeded	Wait a minute and retry
`500`	Server error	Contact support

Formula AI API documentation