Skip to content

Exploring the API

vars_client.generated wraps six full APIs. The Reference section (in the nav) documents every endpoint and data model, one page of endpoints and one page of models per service — but it isn't hand-written: it's generated by scripts/gen_api_reference.py, which reads each specs/<service>.yaml for descriptions and grouping, then statically analyzes the actual generated Kiota code (src/vars_client/generated/) to work out the real Python call for each one. That's a deliberate choice over linking to a live Swagger UI: an institution's own deployment can rename or remove its interactive docs, but the committed spec and generated code can't drift out from under this project — so the reference is regenerated by just docs-build and can never point at a call that doesn't exist.

Reading a reference entry

Every entry follows the same shape:

### Find associations by its videoReferenceUuid and linkName

`GET /v1/associations/{videoReferenceUuid}/{linkName}`

result = await client.annosaurus.v1.associations.by_association_uu_id(association_uu_id).by_link_name(link_name).get(request_configuration)

Returns: Optional[list[AssociationSC]]
Errors: 400 BadRequest · 404 NotFound · 500 ServerError
  • The heading and METHOD /path line come straight from the OpenAPI spec.
  • The Python snippet is the actual call chain, extracted by walking the generated builder classes — including Kiota's occasional naming quirks (e.g. a path parameter landing on a method named for a different, sibling operation's parameter, as above). If it looks odd, that's because it's real, not a copy-editing slip.
  • Returns and Errors name the real generated model classes for the response body and each documented error status, cross-linked in each service's Models page.
  • When an endpoint takes query parameters, the snippet shows the actual generated RequestConfiguration subclass to construct — Kiota doesn't expose query parameters as plain keyword arguments, so this is the one part of the API that isn't obvious from the call chain alone.

The chain-navigation pattern, in general

If you already know an endpoint's path and want to work out the call yourself rather than looking it up: Kiota mirrors the OpenAPI path 1:1 as chained attributes — each fixed path segment is a nested property, each {param} segment becomes a by_<name>(value) method, and the HTTP verb is the terminal method (.get(), .post(body), .put(body), .delete()). Panoptes has an extra leading panoptes segment in its chains (client.panoptes.panoptes.v1...) because its OpenAPI paths are declared as /panoptes/v1/... — see Client.

Your editor will get you there faster than memorizing this, though: every generated method and field is fully typed with the spec's own summary/description as its docstring, so autocomplete + hover on client.annosaurus.v1. is usually quicker than a lookup here.

Keeping the reference current

The reference is a build artifact, not committed to the repo (see docs/reference/ in .gitignore). Regenerate it after pulling in spec changes:

just fetch-specs   # refresh specs/*.yaml, if the upstream spec changed
just generate      # regenerate src/vars_client/generated/
just docs-generate # regenerate docs/reference/ from the two above

just docs-build runs docs-generate automatically, as does the CI docs deploy — see Development.