BlackLab Server REST API reference

This documents all of BlackLab Server's endpoints. For a more guided introducion, see the overview.

General notes

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""?"

Root endpoint

This endpoint returns available corpora and server information.

• Corpora and server information : GET /blacklab-server

Corpus-related endpoints

These endpoints deal with a specific corpus.

All URLs should start with /blacklab-server/<corpus-name>.

Information about the corpus

Information about the corpus such as size, documentFormat, fields, and status.

• Corpus information : GET /
• Corpus status : GET /status
• Field information : GET /fields/<fieldname>
• Span and relation types : GET /relations

Find hits or documents

Search for individual matches of a text pattern, or for documents matching criteria.

• Find hits / group hits : GET /hits
• Parse a pattern without searching : GET /parse-pattern
• Find documents / group documents : GET /docs

Information about a document

Retrieve metadata and (parts of) the content of a document.

• Document metadata : GET /docs/<pid>
• Document contents : GET /docs/<pid>/contents
• Document snippet : GET /docs/<pid>/snippet

Other search

• Term frequencies : GET /termfreq
• Autocomplete : GET /autocomplete

Manage user corpora

If user authentication and private user corpora are enabled, these can be used to manage the user's own corpora: creating/deleting, adding data and sharing.

All URLs should start with /blacklab-server.

• Create user corpus : POST /
• Delete user corpus : DELETE /<corpus-name>
• Add data to user corpus : POST /<corpus-name>/docs
• Get user corpus sharing settings : GET /<corpus-name>/sharing
• Update user corpus sharing settings : POST /<corpus-name>/sharing
• List corpora shared with me : GET /shared-with-me

Other global endpoints

These endpoints are not tied to a specific corpus. All URLs should start with /blacklab-server.

Input format endpoints

These give you information about input format configurations that BlackLab has access to: built-in formats, external format configuration files it found, and user formats if available.

There's also operations to add, update and delete private user formats; those are only available if user authentication and private user corpora are enabled.

• List input formats : GET /input-formats
• Add or update input format : POST /input-formats
• Input format configuration: GET /input-formats/<name>
• Input format XSLT: GET /input-formats/<name>/xslt
• Delete input format : DELETE /input-formats/<name>

Debug endpoints

Can only be used in debug mode.

• Show results cache: GET /cache-info
• Clear results cache: POST /cache-clear

Miscellaneous

• An incomplete list of response codes Blacklab Server will return.