Skip to content

BlackLab Server REST API reference

API compatibility

Use api=3 or api=4 to specify the API version to use. Differences from 3 to 4 are minor; some inconsistencies are fixed and some redundant information was removed from responses. Configure parameters.api in your blacklab-server.yaml to set the default version to use. Support for older version(s) is a transitionary measure and will eventually be dropped.

Full details can be found in API versions.

Output format

To request a specific output format, either:

  • pass the HTTP header Accept with the value application/json, application/xml or text/csv, or
  • pass the query parameter outputformat with the value json, xml or csv.

If both are specified, the parameter has precedence.

Notes about CSV

For CSV hits/docs results, the parameters csvsummary determines whether to include a summary of the search parameters in the output [no] and csvsepline determines whether to include a separator declaration that will help Microsoft Excel read the file [no].

listvalues can be a comman-separated list of annotations to include in the results. listmetadatavalues is the same for metadata fields.

If a metadata field has multiple values (e.g. if a document has multiple authors), they will be concatenated with | as the separator. |, \n, \r and \\ will be backslash-escaped.

As is common in CSV, values may be double-quoted if necessary (e.g. if a value contains a comma). Any double quotes already in the values will be doubled, so say "yes", or "no"? will become "say ""yes"", or ""no""?"

Endpoints

The rest of this section documents all of BlackLab Server's endpoints. For a more guided introducion, see the overview.

Apache license 2.0