Getting started

The Teleport API is organized around RESTopen in new window. It uses standard HTTP verbs, authentication and response codes. It accepts JSONopen in new window-encoded request bodies and also returns JSON-encoded responses. To describe requests and responses, this documentation display them as Typescriptopen in new window interfaces.

The base URL of the Teleport API is https://api.teleport.withthegrid.com.

Autentication

The Teleport API uses tokens to authenticate requests. You must send an Authorization header (Authorization: Bearer [token]) with your request.

TIP

If you do have a Teleport but no token, contact us at support@withthegrid.com to get one.

Encoding

As stated in the introduction, request and response bodies are JSONopen in new window-encoded. Date-objects in JSON should be communicated as ISO 8601 stringsopen in new window, specifically as yyyy-mm-ddThh:mm:ss[.mmm]Z.

Errors

Errors are returned by using the 4xx (for client side) and 5xx (for server side) HTTP status codes. The response contains a JSON-encoded body: { key: string, details?: unknown }. The key is unique for the HTTP status code and can be used for automated client side error handling. The details property (if present) contains debugging information that can help fixing the issue. Specific routes can return specific errors, which are listed with that route. In addition, every route can return the following generic errors.

GENERIC ERRORS
400 { key: "payload_not_readable" }
Payload (body) of the request is not readable, for reasons like an unsupported encoding or invalid size.

400 { key: "payload_not_json" }
Payload (body) cannot be decoded to JSON.

400 { key: "payload_invalid" }
Payload (body) does not adhere to the schema. Provided issues have a schema as listed at https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md.

400 { key: "query_invalid" }
The query string does not adhere to the schema. Provided issues have a schema as listed at https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md.

400 { key: "params_invalid" }
The dynamic components in the URL do not adhere to the schema. Provided issues have a schema as listed at https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md.

401 { key: "unauthorized" }
You're not authorized to do this request

401 { key: "invalid_ip" }
You're not authorized to do this request because your IP is not whitelisted

404 { key: "not_found" }
The server cannot find the requested resource

413 { key: "payload_too_large" }
Payload (body) too large. The request is limited at 25mb.

499 { key: "client_closed_request" }
Client closed request. You will never see this, as you closed the connection ;)

500 { key: "internal_server_error" }
An internal server error happened.