API contract

Preview, insertion confirmation और periodic table के routes।

Authentication और Origin

हर /v1/* route में X-Formulix-Chave भेजें। Key active हो और Origin का hostname खाते के domains या subdomains में हो। Browser Origin भेजता है; JavaScript से इसे manually set न करें। Valid origin के बिना request अस्वीकार होती है।

OPTIONS preflight किसी खाते में registered origins या development origins, GET/POST और Content-Type/X-Formulix-Chave headers स्वीकार करता है। वास्तविक call फिर key के मालिक खाते का domain जाँचती है। Responses में Vary: Origin और Cache-Control: no-store हैं। Allowed origin वापस भेजा जाता है, wildcard नहीं। Denied origin browser में केवल CORS error के रूप में दिख सकता है।

Key public है, admin key नहीं; browser के बाहर Origin जाली किया जा सकता है। Revocation और domain changes default में लगभग 5 seconds में reload होते हैं।

POST /v1/calc — preview

JSON body: { op, dados, idioma, notacao }। op operation चुनता है, dados उसके parameters देता है। Default language en है; हिन्दी के लिए hi भेजें। notacao optional है, जैसे { "decimal": "." }। Operation के अनुसार JSON में HTML, LaTeX, SVG या सहायक data मिलता है। सफल call 1 preview और 0 insertions गिनती है।

const response = await fetch('https://api.formulix.example/v1/calc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Formulix-Chave': 'YOUR_PUBLIC_KEY'
  },
  body: JSON.stringify({
    op: 'word', dados: { html: '<p>कोई समीकरण नहीं</p>' },
    idioma: 'hi'
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.erro);
// इस उदाहरण में: { eqs: [] }

मान्य operations: divisao, multiplicacao, adicao, subtracao, ruffini, mmc, fatoracao, fracoes, regra3, eq1, eq2, sistema, tabela, estudo, grafico, qeq, qmassa, qdist, qvid, qtit, qpaul, qorg, qcad, qtab, word। ये code identifiers हैं; इनका अनुवाद न करें। dados fields operation के अनुसार बदलते हैं; adapter से request बनाएँ। Parameters का एक ही schema नहीं है।

POST /v1/inserir — अंतिम output

Body में tipo, नीचे के specific fields और optional idioma/notacao हैं। Response JSON का common envelope नहीं है।

// सूत्र का body; preview वाले headers ही भेजें।
{
  "tipo": "formula",
  "latex": "x^2",
  "bloco": false,
  "idioma": "hi"
}
// 200 response: { "html": "<math ...>...</math>" }

Client SVG को PNG में बदलकर platform से upload करता है। Calculation API images store नहीं करती। हर accepted confirmation गिनी जाती है, re-edit भी; ID से idempotency नहीं है। पहली confirmation स्वीकार हुई या नहीं पता न हो तो उसे स्वतः दोहराने से बचें।

GET /v1/tabela?idioma=hi

Periodic table के लिए elements का array { z, s, nome, pos, cor } लौटाता है। Public data होने पर भी valid key और Origin चाहिए। Preview/insertion नहीं गिनता; प्रति मिनट limit लागू है। Default language English है।

Limits

• Body अधिकतम 15 MiB। बड़े request में 413 response के बाद connection बंद हो सकता है।
• हर process में प्रति key 1,200 requests/मिनट, previews और table सहित। कई processes हों तो यह global limit नहीं है।
• Free 500 / Starter 5,000 / School 25,000 insertions; Network में संख्यात्मक ceiling नहीं। Free में account और domain दोनों के ceilings हैं; paid usage खाते में जुड़ता है।
• Development: default 300 insertions/माह/खाता, FORMULIX_DEV_LIMITE से configurable। localhost, .localhost subdomains, 127.0.0.1, [::1] और .test शामिल हैं। Valid key फिर भी चाहिए।
• Processes में usage default में हर 5 seconds sync होता है; हर request पर global transactional counter नहीं है। महीना UTC में है।

Errors

Application errors JSON { "erro": "message" } देते हैं। Calculation validation के कुछ messages localized हो सकते हैं।

/saude बिना authentication { "ok": true } देता है; इससे किसी key का access प्रमाणित नहीं होता।