DeclarION REST API

Authentication and quotas

Header	Purpose
`X-API-Key`	Identifies the user profile, quota, priority, timeout limit, and visible sessions.
`Content-Type: application/json`	Required for JSON `POST` bodies.
`X-Web-View: 1`	Optional UI hint used by browser pages; not required for scripts.
`public-key`	Public testing key.

Quotas and submission limits are determined by the key profile.

GET/api/whoami

Check which profile the key resolves to, including quota and role flags.

curl -s "$DECLARION_API/api/whoami" \
  -H "X-API-Key: $DECLARION_KEY"

POST/api/jobs

Submit an interactive fragmentation job. Omitted fields use the server defaults shown in the UI.

curl -s "$DECLARION_API/api/jobs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DECLARION_KEY" \
  -d '{
    "smiles": "NC(=O)NCCCC([NH3+])C(O)=O",
    "mz": 116.0706,
    "mass_tol": 0.0005,
    "layers": 2,
    "num_solutions": 100
  }'

GET/api/status?session=<id>

Poll a job/session. When complete, session.results.fragments contains fragments, rules files, ranking, and PDF status.

curl -s "$DECLARION_API/api/status?session=<job_id>" \
  -H "X-API-Key: $DECLARION_KEY"

GET/api/jobs

List recent jobs visible to the current key. Admin/view-all keys see more than ordinary keys.

curl -s "$DECLARION_API/api/jobs" \
  -H "X-API-Key: $DECLARION_KEY"

POST/api/jobs/<id>/fragments/<n>/pdf?mode=rdkit

Generate or reuse a cached fragment PDF. Use mode=rdkit or mode=mod.

curl -s -X POST "$DECLARION_API/api/jobs/<job_id>/fragments/1/pdf?mode=rdkit" \
  -H "X-API-Key: $DECLARION_KEY"

GET/api/jobs/<id>/fragments/<n>/pdf?mode=rdkit

Check PDF readiness. A done response includes pdf_url; files under /api/files/... are served directly.

curl -s "$DECLARION_API/api/jobs/<job_id>/fragments/1/pdf?mode=rdkit" \
  -H "X-API-Key: $DECLARION_KEY"

GET/api/presets

List configured preset peaks and their ground-truth annotations.

curl -s "$DECLARION_API/api/presets" \
  -H "X-API-Key: $DECLARION_KEY"

POST/api/status

Fetch preset mapping/status in one call by passing the preset list and optional session_id.

curl -s "$DECLARION_API/api/status" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DECLARION_KEY" \
  -d '{"session_id":"<job_id>"}'

Common payload fields for `POST /api/jobs`

Field	Default	Meaning
`smiles`	required	Precursor SMILES. Charged precursors are accepted.
`mz`	required	Target fragment m/z value.
`mass_tol`	`0.0005`	Mass tolerance around the target m/z.
`layers`	`2`	Maximum graph-edit depth.
`num_solutions`	`10`	Maximum number of candidate fragments returned.
`cycle_penalty`	`0`	Optional structural objective penalty.