API documentation
Overseer has an HTTP API, so your own scripts and tools can do what a person does on screen. This page explains what the API covers and how access to it is granted and limited.
What the API is for
Overseer has an HTTP API. What the screens do, the API does: the screens and the API work on the same records and follow the same rules.
You can use it to:
- read and manage computers, tenants and people;
- create and change deployments;
- start maintenance sessions and read their results;
- read inventory, such as the software on a computer;
- connect Overseer to the other tools you run.
Requests use standard HTTP methods, and answers come back as JSON. Lists can be sorted, filtered and read a page at a time. A standard HTTP status code says whether a request succeeded, and a refused request explains why.
How access is granted
Access is granted with tokens. Create a token under Show more, in OAuth Tokens, and give it to the script or tool that calls the API.
Treat a token as you treat a password. Keep it out of scripts that other people can read, and create a separate token for each tool, so you can withdraw one without disturbing the rest.
What a token can do
A token is limited by the role behind it. It can see and do what that role allows, and nothing more. Client separation applies as it does on screen: a token whose access is limited to one client cannot reach another client's computers, deployments or history.
Give each token the narrowest role that lets its tool do the job. A tool that only reads reports does not need a role that can change deployments.
The audit log records work done through the API as it records work done on screen.