Developers

Use the same mapping contract from code.

Normalize one value synchronously through the public API. Every result identifies the taxonomy version, mapping build, decision, and selected concept.

POST/v1/taxonomies/openalex_topics/normalize

Environment: Public demonstration
Authentication: None here
Request shape: One synchronous value

Response

Not sent

Send the request to see the complete response.

curl "https://your-canonmap-host/v1/taxonomies/openalex_topics/normalize" \
  -H "Content-Type: application/json" \
  --data-raw '{"value":"artificial intelligence for healthcare diagnosis","include_candidates":5}'

Normalize resource

One synchronous mapping decision

POST /v1/taxonomies/{taxonomy_id}/normalize

Request fields
Field	Type	Meaning
`value`	`string`	One non-empty source label or short description.
`context`	`object \| null`	Optional string-to-string evidence about this individual record.
`include_candidates`	`integer`	Candidate rows returned for inspection: 0 through 10. Default: 5.

Response fields
Field	Type	Meaning
`taxonomy_id`	`string`	Stable identifier for the target vocabulary.
`taxonomy_version`	`string`	Exact source-vocabulary version used for the decision.
`source_value`	`string`	Original submitted value, unchanged.
`decision`	`match \| ambiguous`	The semantic outcome. Ambiguous is a valid decision, not a transport error.
`concept`	`object \| null`	Selected concept for a match; otherwise null.
`concept.id`	`string`	Stable concept ID. Retain this instead of relying on the display label.
`concept.label`	`string`	Display label from the selected taxonomy version.
`candidates`	`array`	Retrieved concepts retained for inspection, up to include_candidates.
`mapping_build`	`string`	Immutable identifier for the published mapping build.
`calibrated_probability`	`number \| null`	Build-calibrated estimate for the top candidate. It is not raw similarity.
`reason_code`	`string \| null`	Machine-readable explanation when no concept is returned.
`reason`	`string \| null`	Human-readable explanation when no concept is returned.

Evaluation resource

Read the evidence attached to the published build

GET /v1/taxonomies/{taxonomy_id}/evaluation

The response identifies the taxonomy and mapping build, evaluation and assessed row counts, the automated fit distribution, ambiguity rate, retained examples, decision policy, and evidence basis. It describes the currently published build; it does not start an evaluation job.

View the same evidence in Performance

Operational boundary

Supply the taxonomy and values, not a model configuration

Improvements arrive as new mapping_build values under the same stable response contract.

Available now

Unauthenticated access to the selected demonstration taxonomies.
One synchronous value per public normalization request.
Zero to ten returned candidates for inspection.
A 64 KiB request-body limit at the public web proxy.
429 responses can include Retry-After.

Not implied by this demo

No durable batch jobs or hosted arbitrary-taxonomy upload.
No authentication, tenant isolation, or retention guarantee.
No request history or idempotency contract.
No customer-specific accuracy claim.

Errors

Fail closed and keep transport separate from meaning

A successful response may still have decision: "ambiguous"; branch on that field before using concept. By contrast, every response below is a transport or request failure and never contains a substituted mapping.

Public error behavior
Status	Meaning	Client action
`404`	Unknown public taxonomy	Correct the taxonomy identifier.
`413`	Request body exceeds 64 KiB	Send a smaller synchronous request.
`422`	Malformed body or field outside its allowed range	Correct the request before retrying.
`429`	Shared demonstration rate limit reached	Wait for the returned Retry-After interval.
`502`	Public proxy cannot reach the normalization service	Retry later; no result was substituted.
`503`	Published build is unavailable	Treat this as service failure, not semantic ambiguity.