Skip to content
Buy
Local HTTP API
API, CLI e MCP

Local HTTP API

Generate EPS, SVG and PNG, convert LaTeX and MathML, recognize images and track links through NeoMath's HTTP API, which only serves your own computer and requires a token.

On this page

The local HTTP API is a server that only serves your own computer (127.0.0.1). It is what the InDesign plugin uses, and it also serves scripts and other programs in any language. The reference for each route is in HTTP API reference.

Start#

There are two servers with the same API:

Command For whom Extra routes
NeoMath --servidor the installed app; it is what InDesign uses /v1/ocr, /v1/quimica, /v1/editar, /v1/vinculos
neomath servidor the command line (without the app’s routes) /v1/vinculos; the others answer 501
Terminal
NeoMath --servidor
neomath servidor --porta 8790

The installer can make NeoMath --servidor start with the system (on by default on Windows and Linux). It opens no window and uses the user folder as root.

Option Default What it does
--porta N 8790 port
--token T generated fixed token; without the option, a random 64-character token at each start
--sem-token turns the token off (testing only)
--origem URL none authorized web page origin (repeatable)
--raiz FOLDER off (neomath), user folder (NeoMath) allows /v1/lote, /v1/editar and /v1/vinculos only inside that folder
--threads N 4 simultaneous requests (1 to 16)
--sessao FILE data folder where to write servidor.json

Port and token: servidor.json#

On start, the server writes servidor.json, readable only by the user:

System Path
Windows %LOCALAPPDATA%\NeoMath\servidor.json
macOS ~/Library/Application Support/NeoMath/servidor.json
Linux $XDG_STATE_HOME/neomath/servidor.json or ~/.local/state/neomath/servidor.json
JSON
{ "porta": 8790, "token": "9f2c…", "url": "http://127.0.0.1:8790", "pid": 4242, "versao": "0.2.0" }

Clients read the port and the token from this file.

Authentication#

Every request, except GET /v1/saude, carries the token:

HTTP
Authorization: Bearer <token>

X-NeoMath-Token: <token> and ?token=<token> in the URL also work, for those who cannot send headers.

Examples#

curl

Terminal
TOKEN=$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.local/state/neomath/servidor.json')))['token'])")
curl -s http://127.0.0.1:8790/v1/saude
curl -s -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:8790/v1/svg -d '{"mathml":"\\frac{a}{b}"}' -o eq.svg
curl -s -H "Authorization: Bearer $TOKEN" -X POST "http://127.0.0.1:8790/v1/eps?bruto=1" -d '{"mathml":"\\ce{2 H2 + O2 -> 2 H2O}","opcoes":{"cor":[0,100,100,0]}}' -o reacao.eps

JavaScript

JavaScript
const r = await fetch("http://127.0.0.1:8790/v1/eps", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
  body: JSON.stringify({ mathml: "x^2 + y^2 = r^2", opcoes: { tamanho: 18 } }),
});
const g = await r.json();
console.log(g.largura_pt, g.altura_pt, g.linha_base_pt);

Python

Python
import json, os, urllib.request
s = json.load(open(os.path.expandvars(r"%LOCALAPPDATA%\NeoMath\servidor.json")))
pedido = urllib.request.Request(s["url"] + "/v1/png?dpi=600", data=json.dumps({"mathml": r"\sqrt{2}"}).encode(),
                                headers={"Authorization": "Bearer " + s["token"], "Content-Type": "application/json"})
open("raiz.png", "wb").write(urllib.request.urlopen(pedido).read())

The mathml field accepts MathML or LaTeX: NeoMath recognizes it by itself.

Output options#

Key Example Effect
neqp style text style (fonts, sizes, spacing)
cor "#1F4E79", "red", [0,100,100,0], [31,78,121] equation color (a list of 4 is CMYK)
cor_em_tudo true also paints bars and fractions
tamanho 18 body size in pt (1 to 1000)
fonte "Arial" font for text, variables and numbers

Responses and errors#

Code When
200 success
400 invalid JSON or options
401 no token or wrong token
403 browser origin not authorized, or folder outside --raiz
404 unknown route
413 body larger than 16 MB (64 MB in /v1/lote-zip)
421 Host different from 127.0.0.1:<port> or localhost:<port> (DNS rebinding protection)
422 a construct that is not supported, or an OCR image not recognized
501 a route that only exists on the app’s server
JSON
{ "status": "erro", "codigo": "token", "erro": "token ausente ou inválido …" }

Edit flow#

This is how InDesign keeps equations up to date:

  1. The client generates the EPS with "formato": "neof" and writes it into the document.
  2. It calls POST /v1/editar with the path; the app opens the file and returns modificado_ms and tamanho.
  3. It polls POST /v1/vinculos every 2 seconds.
  4. When the date or size change, the file was saved in NeoMath: the client updates the link and recovers the new code with /v1/abrir and /v1/para-latex.

Security#

  • Listens only on 127.0.0.1 and rejects another Host.
  • Browser requests are only accepted from origins passed in --origem.
  • Routes that touch the disk are tied to the --raiz folder (with symbolic links resolved).
  • The old routes without /v1 keep working for old clients, also with a token.