Skip to main content

​
Overview

This section describes how to use the Diversion API to build custom integrations and clients.

​
Authentication

All API endpoints, unless stated otherwise, are authenticated using Bearer tokens. 
Authorization: Bearer <token>

​
Base URL

All API endpoints are relative to the base URL https://api.diversion.dev/v0.

​
Making Your First Request

Once you have your token, you can test that it works by making a request to the /auth/test endpoint: 
import requests

response = requests.get(
    "https://api.diversion.dev/v0/auth/test",
    headers={"Authorization": "Bearer <token>"}
)
print(response.status_code)  # Should print 204

​
Real-World Example: Create a New Repo

See the endpoint’s full documentation here. 
import requests

response = requests.post(
    "https://api.diversion.dev/v0/repos",
    headers={"Authorization": "Bearer <token>"},
    json={
        "name": "my-repo",
        "description": "My first repo"
    }
)
print(response.json())  # Should print the created repo

​
Error handling

Some common errors can be returned from most API endpoints and are listed below. Errors that are specific to an API endpoint are listed in the endpoint’s documentation.

​
Error format

All errors are returned in the following format: 
{
  "detail": "<detailed description of the error>",
  "status": <status code>,
  "title": "<short, human-readable summary of the error type>"
}

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "A detailed description of the error"
    },
    "status": {
      "type": "integer",
      "description": "HTTP status code",
      "examples": [400, 401, 403, 404, 500]
    },
    "title": {
      "type": "string",
      "description": "A short, human-readable summary of the error type"
    },
  },
  "required": ["detail", "status", "title"]
}

​
Common errors

​
400 Bad Request

Returned when the request is invalid. Example response: 
{
  "detail": "'d' is too short\n\nFailed validating 'minLength' in schema:\n    {'type': 'string',\n     'example': 'example_id',\n     'minLength': 3,\n     'maxLength': 128}\n\nOn instance:\n    'd'",
  "status": 400,
  "title": "Bad Request"
}

​
401 Unauthorized

Returned when the authentication token is invalid or expired. Example response: 
{
  "detail": "Invalid authentication token",
  "status": 401,
  "title": "Unauthorized"
}

​
403 Forbidden

Returned when the authentication token is valid but the user is not authorized to access the endpoint. Example response: 
{
  "detail": "User not authorized to perform the requested action on the resource",
  "status": 403,
  "title": "Forbidden"
}

​
404 Not Found

Returned when the requested resource is not found. Example response: 
{
  "detail": "Workspace id not found",
  "status": 404,
  "title": "Not Found"
}

​
500 Internal Server Error

Returned when the server encountered an unexpected condition that prevented it from fulfilling the request. Example response: 
{
  "detail": "Internal server error",
  "status": 500,
  "title": "Internal Server Error"
}