Getting started

The Teleport API is organized around REST. It uses standard HTTP verbs, authentication and response codes. It accepts JSON-encoded request bodies and also returns JSON-encoded responses. To describe requests and responses, this documentation display them as Typescript 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 JSON-encoded. Date-objects in JSON should be communicated as ISO 8601 strings, 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. Details are provided in the details property.

---

400 { key: "query_invalid" }

The query string does not adhere to the schema. Details are provided in the details property.

---

400 { key: "params_invalid" }

The dynamic components in the URL do not adhere to the schema. Details are provided in the details property.

---

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.