HTTP API basics

Call the Vis gateway with HTTP requests from any language. This page shows how to get the OpenAPI document, authenticate requests and read gateway errors. Each feature page shows the requests for its tasks.

When to use

Your program is not written in Python. Authenticate requests. Then open the API page of your feature, for example Sessions API, and select HTTP at the top of that page.
You need the exact request and answer formats. Get the OpenAPI document.
A request fails with an error status. Handle gateway errors.

To use typed calls from Python, read Python SDK. To install and run the gateway, read Running a gateway.

Before you start

Start a gateway. For a gateway on another computer, follow Connect from another machine and get its token from the operator through a secure channel.

Get the OpenAPI document

The gateway serves its OpenAPI 3.1 document without a token:

curl -sS http://127.0.0.1:7890/openapi.json -o vis-gateway.json

Use the document for routes, request formats and answers. The feature pages explain when to use each request.

Authenticate requests

Each request needs these headers:

x-vis-protocol with the protocol number of the gateway. GET /v1/capabilities returns it as protocol.protocol. An incompatible client receives HTTP 426.
Authorization: Bearer <token> when the gateway requires a token. Tokens and HTTP 401 tells when it does.

This setup reads the token and the protocol number once. The vis_api function then sends both headers. The feature pages use this function in their examples. Do not print or commit the token.

export VIS_GATEWAY_URL=http://127.0.0.1:7890
export VIS_GATEWAY_TOKEN="$(cat "$HOME/.vis/gateway.token")"
export VIS_PROTOCOL="$(curl -sS -H "Authorization: Bearer $VIS_GATEWAY_TOKEN" \
  "$VIS_GATEWAY_URL/v1/capabilities" |
  python3 -c 'import json, sys; print(json.load(sys.stdin)["protocol"]["protocol"])')"

vis_api() {
  curl -sS -H "x-vis-protocol: $VIS_PROTOCOL" -H "Authorization: Bearer $VIS_GATEWAY_TOKEN" "$@"
}

Handle gateway errors

An error answer has a JSON body with error.type and error.message:

{"error": {"type": "unauthorized", "message": "missing or invalid bearer token"}}

Status	When
`401`	The token is missing or not correct.
`426`	The type is `incompatible_protocol`. The client and the gateway have no common protocol. Update the client or the gateway to compatible versions.
Other `4xx` and `5xx`	The feature page of the route explains the `type`.