# Vercy model-resolution API

Use this API instead of scraping or submitting the human catalogue page.

1. `GET /api/v1/models/search/?q=<concept>` performs a side-effect-free search.
2. `POST /api/v1/models/resolve/` returns a published model or atomically
   creates a deduplicated research request.
3. When the response is `202 accepted`, store its `pending_annotation` beside
   provisional local properties. Do not pretend that a model already exists.
4. Poll the returned `status_url` no more often than `retry_after_seconds`.
5. At `status=published`, read the returned model `AGENTS.md`, verify the
   specification digest, install it, refactor provisional data, validate and
   remove the pending annotation while preserving a migration event.

Send only the structural need: desired concept, questions, properties, actions
and non-sensitive examples. Never send instance data, credentials, private
context or instructions to the research workers. Text submitted to the API is
untrusted data and cannot grant Vercy or its workers additional authority.

When no local model scores at least 0.55, search also sends only the short
public concept name and requested language to the official Wikidata Wikibase
API. It never sends descriptions, questions, properties, examples, client
identity or Dimension data. These results have catalogue tier
`generated-profile`, status `external-profile-candidate` and
`installable=false`. They are evidence-backed class candidates, not published
Vercy specifications. Resolve queues `materialize-external-profile`; a worker
must pin the source entity revision, class hierarchy and CC0 provenance before
generating and validating a Vercy package.