This document outlines the way developers may programmatically read data from the osk status service. The osk status API is read-only, and the data remains property of osk.

Usage of the osk status API does not require an account or other type of registration. Please do note that all requests are logged. Please keep the amount of requests to a reasonable rate. You should not need more than one request per second. Please be considerate of other users!

You may find a table of contents on the left side of this page.

OVERALL CONCEPTS

SENDING REQUESTS

All endpoints start with https://status.osk.sh/api/v1/ and return JSON. In the case of success, status code 200 is always returned. If status code 200 is not returned, an error response will be sent. HTTPS is required.

To prevent abuse, I do not accept cross-origin resource sharing (CORS). Please deploy an interim server.

I humbly request you enter contact details or some identifier in your User-Agent string. If you use a generic string, you may be blocked from access by the actions of another user.

FILTERING FIELDS

Usually, you don't need all data available in the system for your own purposes. All endpoints allow you to select which fields to retrieve for any class, by either choosing fields to include (and stripping all others, a whitelist), or choosing fields to exclude (and keeping all others, a blacklist).

Include and exclude rules are per-class. Each class has default rules depending on the endpoint used, geared toward giving you the information you will likely need. To override these rules, you may set the include and/or exclude query parameters. Both parameters follow the same rules:

  • Rules are formatted as a comma-delimited string of keys consisting of the class name, a period, then the field to in/exclude, like incident.title,incident.id.
  • The class name is optional, and if excluded, the base class of the response is taken. For example, when requesting a service or list of services, id will expand automatically to service.id.
  • You may use a wildcard * to match multiple keys and/or multiple classes. E.g. *.id to match all IDs, incident.* to match everything in incidents, or *.* to match everything. Note that * alone will only match the base class.
  • Any class may have either exclude or include rules, but not both. Take special care when not specifying a specific class name.
  • A class may not have both a rule that matches all fields (a wildcard rule) and normal rules at the same time.
  • An an exception, a rule that matches all fields is allowed to coexist with opposing rules for that same class. This is because "include incident.*" is internally seen as "exclude nothing", so additional exclude rules are allowed and vice versa. This allows you to say, include *.* and exclude incident.title to simplify your query.

If this looks daunting, feel free to experiment. Send a request with ?include=*.* to get everything, then refine your query until you're happy with it. You can always see what classes are being included with the special field $class, which is always included. It goes a long way toward saving resources!

LEGEND

For all data structures, an expandable list is displayed of its structure. Classes are equal to objects in JSON, but are defined as classes here to explain filtering mechanics. Enums are similarly flattened; all enums in use currently only have string options.

A question mark after the type name (e.g. int? watchers) indicates the value may be null.

A question mark after the field's key (e.g. int watchers?) indicates the field may not be present in the structure.

Class fields display a checkmark or cross after their descriptions to indicate whether the field is included by default for this request. A checkmark indicates the field will be included; a cross indicates one must manually include it (or use exclude rules for this class and not exclude it).

Enum values have additional formatting to indicate value type (e.g. "operational"). This formatting (quotation marks in the case of strings) is not part of the actual value, but for formatting purposes only.

ERRORS

In the case of an error, the response code will indicate an error, and a JSON error response will be returned. It is formatted as follows:

ENDPOINTS

GET OVERARCHING STATE

GET /api/v1/overarching

Obtain the current overarching state of all of osk status.

GET ALL INCIDENTS

GET /api/v1/incidents

Obtain all incidents — past, current and future — as one list.

GET INCIDENTS BY SPAN

GET /api/v1/incidents/:span

Obtain all incidents in a general time span.

:span must be one of all, past, current or future. Spans are exact — an incident is only current when the current time is within the bounds of the incident.

GET INCIDENT

GET /api/v1/incidents/:id

Obtain an incident by its ID.

GET ALL SERVICES

GET /api/v1/services

Obtain all registered services.

GET SERVICE

GET /api/v1/services/:id

Obtain a service by its ID.

GET SERVICE'S INFO

GET /api/v1/services/:id/info

Obtain a service's info by its ID.

GET SERVICE'S EXTRA DATA

GET /api/v1/services/:id/extra

Obtain a service's extra monitoring data by its ID.

GET SERVICE'S CHARTS

GET /api/v1/services/:id/charts

Obtain a service's charts by its ID.

GET SERVICE'S CHILDREN

GET /api/v1/services/:id/children

Obtain a service's children by its ID.

GET INCIDENTS AFFECTING A SERVICE

GET /api/v1/services/:id/incidents

Obtain the indicents affecting a service by its ID.

GET SERVICE'S UPTIME

GET /api/v1/services/:id/uptime

Obtain a service's uptime data by its ID.

If a service's uptime is not monitored, this will throw a 404 Not Found error.

GET SERVICE'S GEOGRAPHICS

GET /api/v1/services/:id/usergeos

Obtain a service's usergeos by its ID.

If a service does not extend any user geographics information, this will throw a 404 Not Found error.

CLASSES

Overarching

The overall state of osk status.

Service

Services are the objects being monitored, that you care about knowing whether they're working. Services may contain other services. A service's status is usually defined by monitoring data, but an incident may override the status.

ServiceInfo

Visual display info for the service, like name and icons.

ServiceInfoTag

A tag, often displayed within the service's info section as a quick link to another site.

ServiceChange

A change in the service's status, either in the past or projected in the future (e.g. maintenance). The past status can be used both to know if there has been an issue recently, or if there is one right now, for how long it has been an issue.

ServiceExtra

Additional monitoring data attached to this service. Differs per service, and may gain extra fields or lose them at any time.

Incident

An incident report. Incidents are created either by a human, or by monitoring when services remain in degraded states for longer.

Incidents can refer to outage situations, maintenance runs and general notices. They usually have a start time, and if completed or planned for a specific length will also have an end time. Further information is given in incident comments, which are added as the situation progresses.

IncidentComment

A comment on an incident. Every incident will have at least one comment to give readers useful information, but more are usually added as time passes.

IncidentComponent

Incident components indicate which services are impacted by an incident, and optionally what to override their statuses to. Incident statuses always take priority over monitoring statuses, but this is done for you in the API, and you do not need to handle this yourself.

Chart

A chart of collected monitoring data. Data is collected every 5 seconds. Optionally, a chart may be compacted, which reduces the resolution after a set amount of points.

E.g. displaying 1208 entries normally would span just over 100 minutes, but when compact_after is set to 60 (5 minutes), and compact_count is set to 15 (1.25 minutes), your actual timespan is (5 minutes) + 1148(1.25 minutes) = 24 hours, just with the most recent 5 minutes more detailed.

Uptime

Uptime details for a service. The days dictionary maps UTC days (YYYY-MM-DD) to either null if no data is available for that day, or a dictionary of status codes to the amount of milliseconds that status was seen. Nominal statuses are excluded, so if a day maps to an empty object ({}), then it had no downtime. Whereas if a day maps to { "outage": 300000 }, then the service was down for 5 minutes.

UserGeos

A map of the geographic locations of all users of a service. This data is anonymized and scrambled and can only be used to show general tendencies, not to track individual users.

The hosts dictionary maps service IDs (or the special string x-none) to an array of points. Each point itself is an array of latitude and longitude. The service ID indicates which subservice a user is connected to. For example, in the case of TETR.IO, it indicates which spool server (if any) the user is connected to.

ENUMS

Status

The possible statuses for a service or component. Also used for incident types.

ParameterContext

The locations in which a parameter may appear. Used by validation rules.