> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Guide

> Getting started with Diversion API

## 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:

<CodeGroup>
  ```python Python theme={null}
  import requests

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

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

  ```bash cURL theme={null}
  curl -X GET "https://api.diversion.dev/v0/auth/test" \
    -H "Authorization: Bearer <token>"
  ```

  ```go Go theme={null}
  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
  }
  ```

  ```csharp C# theme={null}
  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
  ```
</CodeGroup>

## Real-World Example: Create a New Repo

See the endpoint's full documentation [here](/api-reference/repository-management/create-a-repo).

```python theme={null}
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:

```json theme={null}
{
  "detail": "<detailed description of the error>",
  "status": <status code>,
  "title": "<short, human-readable summary of the error type>"
}
```

<Accordion title="View JSON Schema">
  ```jsonschema theme={null}
  {
    "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"]
  }
  ```
</Accordion>

### Common errors

#### 400 Bad Request

Returned when the request is invalid.

Example response:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "detail": "Internal server error",
  "status": 500,
  "title": "Internal Server Error"
}
```