Developer Guide

Overview

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

Authentication

Generate an API token from Settings > Integrations in the Diversion web app. Tokens start with dvk_, are shown only once, and can be revoked individually. See Generate an API Token for instructions. API access requires the Pro plan or above. 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

const response = await fetch("https://api.diversion.dev/v0/auth/test", {
  headers: {
    "Authorization": "Bearer <token>"
  }
});
console.log(response.status);  // Should print 204

curl -X GET "https://api.diversion.dev/v0/auth/test" \
  -H "Authorization: Bearer <token>"

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.diversion.dev/v0/auth/test", nil)
    req.Header.Set("Authorization", "Bearer <token>")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    fmt.Println(resp.StatusCode)  // Should print 204
}

using System;
using System.Net.Http;
using System.Threading.Tasks;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer <token>");

var response = await client.GetAsync("https://api.diversion.dev/v0/auth/test");
Console.WriteLine((int)response.StatusCode);  // 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>"
}

View JSON Schema

{
  "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": "'st' 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"
}

⌘I

API Documentation

Authentication

Account

Repository Management

Repository Manipulation

Perforce Repository Import

Repository Commit Manipulation

Repository Workspace Manipulation

Repository Branch Manipulation

Repository Tag Manipulation

Repository Granular Permissions

Repository Shelves Manipulation

Repository Draft Commits

File Mutation

Repository Merge Manipulation

Collaborators

Repository Content Comparison

Organization Management

User Management

Reviews

Overview

Authentication

Base URL

Making Your First Request

Real-World Example: Create a New Repo

Error handling

Error format

Common errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

​Overview

​Authentication

​Base URL

​Making Your First Request

​Real-World Example: Create a New Repo

​Error handling

​Error format

​Common errors

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

Overview

Authentication

Base URL

Making Your First Request

Real-World Example: Create a New Repo

Error handling

Error format

Common errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error