GET /api/v1/
What this API is, where to start, and the daily allowance
Parameters: none
The HumanToll API
Everything the pages show, as JSON, with the same apparatus — free, unauthenticated and read-only.
Send GET requests to https://quiescence.eu/humantoll/api/v1/. Every response carries its status, scenario, run, methodology and data version, metrics, the sources behind it with their licences, the licence the response may be reused under, caveats and a citation. Until a validated run is published, figures are withheld and every response says so.
Where it stands
No figure is published yet. The API answers with the register — products, bills of materials, materials, conflicts, countries, channels, scenarios, sources — and every figure is null, with the reason beside it.
Start here
GET /api/v1/— what the API is, its endpoints and the daily allowanceGET /api/v1/product/croissant— one product: both metrics on both routes, its bill of materials, and the chain it reachesGET /api/v1/compare?a=electric-car&b=petrol-car— two products drawn together: the interval of their ratioGET /api/v1/spend?category=07&amount=250— €250 of EU households’ spending on transportGET /api/v1/openapi.json— this API as an OpenAPI 3.1 document
How to quote a figure
- With its interval, every time: "an estimated 0.4–3.5 × 10⁻⁶ deaths per unit", never the central value alone.
- Two significant figures, never more. A figure graded INDICATIVE has no central value (
valueis null,range_onlyis true). - Name the scenario, the run and the methodology version, as every response does.
- Say "attributed to the supply chain of", never "caused by". Production phase only; every figure is a floor.
- Cite as the response’s
citationdoes: HumanToll <year>, run <id>, methodology v<version>. <page URL>
What every response carries
The same keys on every endpoint. A key is never missing; where it has no value it is null, and withheld says why.
status- published, preview (an operator’s view of an unpublished run) or withheld (no figure anywhere in the response).
scenario · run- The attribution scenario, and the run the figures come from: its id, year, input–output system and engine.
methodology_version · data_version- What the run was computed under.
metrics- One product’s figures: deaths and injuries, each on the material route (per unit, per kg) and the monetary route (per €1,000).
data- The endpoint’s own content, in three parts: facts from the register,
recordsfrom publishers’ releases, andresultsthe run computed. withheld- Every part that is not shown, and why: nothing is published yet, or the licence gate refused it.
sources- Every release behind the response, with its licence and the credit its licence requires.
licence- What the response may be reused under: the strictest share-alike licence among its sources. For any figure the model computes, CC BY-NC-SA 3.0 IGO while WHO’s Global Health Estimates are an input.
caveats · citation- What the figures are not, and how to cite them.
A figure
Every figure is an object: value (the central estimate, or null when the grade is INDICATIVE), low and high (the 5th and 95th percentiles of 2,000 draws), confidence (HIGH, MEDIUM, LOW or INDICATIVE), range_only and unit. It is built by the same function that writes every figure on the pages, so the API cannot show a number the pages would refuse.
Endpoints
All GET. Scenario, where it applies, is one of S-MAX (the default), S-EVID, S-RES, S-ARMS and S-CONS. An unknown parameter is refused by name.
GET /api/v1/products
The product catalogue; with a published run, each product's deaths per unit and per kg
Parameters:
tier— semi_finished or finished.
one of:semi_finished·finishedcategory— A product category code, as each product's `category.code` gives it.sort— name, toll (deaths per kg on the material route), confidence or complete.
one of:name·toll·confidence·completescenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/product/{slug}
One product: both routes and both metrics, the bill of materials and the chain it reaches
Parameters:
slug(required) — The product's permanent slug, as in its page's address.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/product/{slug}/contributions
What carries one figure: its breakdown by material, country, conflict, channel or industry
Parameters:
slug(required) — The product's permanent slug, as in its page's address.metric— deaths or injuries.
one of:deaths·injuriesmethod— material (the route through the bill of materials) or mrio (per €1,000).
one of:material·mriotype— One breakdown; all of the route's when absent.
one of:material·country·conflict·channel·sectorscenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/product/{slug}/explain
The audit trail of one figure: every stage, each summing to the headline
Parameters:
slug(required) — The product's permanent slug, as in its page's address.metric— deaths or injuries.
one of:deaths·injuriesscenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/compare
Two products drawn together: the interval of their ratio, and a verdict only where it holds
Parameters:
a(required) — The first product's slug.b(required) — The second product's slug.metric— deaths or injuries.
one of:deaths·injuriesscenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/spend
EU households' spending on each consumption category: the harm in €amount, grouped against all spending
Parameters:
category— A COICOP 2018 category code; all of them when absent.amount— Euros spent; every figure and its interval scale with it.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/material/{slug}
A raw material: who produces it, which products use it, and what it carries in a run
Parameters:
slug(required) — The material's permanent slug, as in its page's address.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/conflict/{slug}
A scored conflict: the deaths UCDP counted, the model's attribution, and the products it reaches
Parameters:
slug(required) — The conflict's permanent slug, as in its page's address.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/country/{iso3}
A country: the harm counted there, and the products it reaches
Parameters:
iso3(required) — ISO 3166-1 alpha-3, in either case.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/channel/{code}
A harm channel: what it counts, how it is attributed, and what it reaches
Parameters:
code(required) — C1 conflict · C2 work · C3 deprivation · C4 exposure.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/scenarios
The five attribution scenarios and their parameters
Parameters: none
GET /api/v1/runs
The published runs; none while figures are withheld
Parameters: none
GET /api/v1/runs/{id}
One published run and the verdict of each validation gate
Parameters:
id(required) — The run id a figure's citation names.
GET /api/v1/methodology
The versions of the methodology
Parameters: none
GET /api/v1/sources
The source register: every source, its licence, and the basis it is used on
Parameters: none
GET /api/v1/search
Find a product, material, conflict, country or channel
Parameters:
q(required) — Two to 64 characters.
GET /api/v1/openapi.json
This API as an OpenAPI 3.1 document, generated from the route table
Parameters: none
Errors
Real status codes, and one shape: {"ok": false, "error": {"code", "message", "detail"}}. The code is stable; detail names the parameter and what it accepts.
400- A parameter is missing, unknown or malformed.
401- A key was presented and is not valid — unknown, revoked or expired. It is refused, never served as if there were none.
404- No such path, product, material, conflict, country, channel, category or published run.
405- Anything but GET, HEAD or OPTIONS.
429- This address has used its requests for today.
500- A fault on our side, logged. A figure that fails its own checks is a 500, never a number.
503- The database is unavailable.
The daily allowance
100 requests a day from one address, reset at 00:00 UTC; every response says how many remain (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). The OpenAPI document is not counted.
No address is stored. The count is kept under a salted hash whose salt is drawn each day and destroyed, with the counts, when the day ends.
HumanToll is a research project, not a commercial service. For advanced API access, contact us at info@quiescence.eu. info@quiescence.eu
With a key
For research that needs more than the daily allowance, a key is issued on request, free of charge: write to info@quiescence.eu with what the work is and how much it needs. Send the key as Authorization: Bearer <key> (or X-API-Key); the allowance then counts per key instead of per address, and each response says how much of it remains.
A key is shown once, when it is issued, and HumanToll keeps only its fingerprint. A lost key is revoked and replaced — there is nothing to recover. A key that is not valid is refused with 401. Send it in a header, never in the URL: URLs are written to logs.
From a browser
Any origin may read the API (Access-Control-Allow-Origin: *). No cookie is set, and none is needed.