# CleanDocs API (v1.0.0) — Complete API Reference

API for managing OpenAPI documentation projects on CleanDocs.dev

**Contact:** CleanDocs Support · [Website](https://cleandocs.dev)

---

## Base URLs

- **`https://api.cleandocs.dev`** — Production API server

---

## Authentication

### bearerAuth

- **Type:** http bearer
- **Format:** API Key

API key authentication. Generate an API key at https://cleandocs.dev/dashboard and use it as: `Authorization: Bearer cd_your_api_key_here`

### sessionAuth

- **Type:** apiKey
- **In:** cookie

Session-based authentication using cookies. Users must be logged in via the web interface.

---

## Projects

Project management endpoints

### GET /projects

**List all projects**

Retrieves a list of all projects belonging to the authenticated user

**Authentication:** bearerAuth, sessionAuth

**Responses:**

#### ✅ 200 — Successful response

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | array[object] | No |  |
| `meta` | object | No |  |

Example:

```json
{
    "success": true,
    "data": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "slug": "my-api",
            "title": "My API Documentation",
            "description": "API documentation for my awesome project",
            "openapi_format": "json",
            "created_at": "2025-01-15T10:30:00+00:00",
            "updated_at": "2025-01-15T10:30:00+00:00",
            "urls": {
                "docs": "https://my-api.cleandocs.dev",
                "json": "https://api.cleandocs.dev/projects/my-api/openapi.json",
                "yaml": "https://api.cleandocs.dev/projects/my-api/openapi.yaml",
                "self_host": "https://api.cleandocs.dev/projects/my-api/self-host.zip"
            }
        }
    ],
    "meta": {
        "total": 1
    }
}
```

#### ❌ 401 — Authentication required

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `error` | string | No | Error message Example: `An error occurred` |

Example:

```json
{
    "success": false,
    "error": "User not found"
}
```


### POST /projects

**Create a new project**

Creates a new project with the provided OpenAPI specification

**Authentication:** bearerAuth, sessionAuth

**Request Body (required):**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | Yes | Project title Example: `My API Documentation` |
| `slug` | string | Yes | URL-friendly identifier (3-64 chars, lowercase letters, numbers, hyphens only) Example: `my-api` |
| `description` | string | No | Optional project description Example: `API documentation for my awesome project` |
| `openapi_content` | string | Yes | OpenAPI specification content in JSON or YAML format Example: `{"openapi":"3.1.0","info":{"title":"My API","version":"1.0.0"},"paths":{}}` |

Example:

```json
{
    "title": "My API Documentation",
    "slug": "my-api",
    "description": "API documentation for my awesome project",
    "openapi_content": "{\"openapi\":\"3.1.0\",\"info\":{\"title\":\"My API\",\"version\":\"1.0.0\"},\"paths\":{}}"
}
```

**Responses:**

#### ✅ 201 — Project created successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `message` | string | No | Example: `Project created successfully` |
| `data` | object | No |  |

Example:

```json
{
    "success": true,
    "message": "Project created successfully",
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "slug": "my-api",
        "title": "My API Documentation",
        "description": "API documentation for my awesome project",
        "openapi_format": "json",
        "created_at": "2025-01-15T10:30:00+00:00",
        "updated_at": "2025-01-15T10:30:00+00:00",
        "urls": {
            "docs": "https://my-api.cleandocs.dev",
            "json": "https://api.cleandocs.dev/projects/my-api/openapi.json",
            "yaml": "https://api.cleandocs.dev/projects/my-api/openapi.yaml",
            "self_host": "https://api.cleandocs.dev/projects/my-api/self-host.zip"
        }
    }
}
```

#### ❌ 400 — Validation error

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `error` | string | No | Example: `Validation failed` |
| `errors` | object | No | Field-specific validation errors Example: `{"title":"Title is required","slug":"Slug must be 3-64 characters and contain only lowercase letters, numbers, or hyphens"}` |

Example:

```json
{
    "success": false,
    "error": "Validation failed",
    "errors": {
        "title": "Title is required",
        "slug": "Slug must be 3-64 characters and contain only lowercase letters, numbers, or hyphens",
        "openapi_content": "OpenAPI content is required"
    }
}
```

#### ❌ 401 — Authentication required

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `error` | string | No | Error message Example: `An error occurred` |

Example:

```json
{
    "success": false,
    "error": "User not found"
}
```


---

## API Keys

API key management endpoints

### GET /keys

**List your API keys**

Retrieves a list of all API keys for the authenticated user

**Authentication:** bearerAuth, sessionAuth

**Responses:**

#### ✅ 200 — Successful response

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | array[object] | No |  |
| `meta` | object | No |  |

#### ❌ 401 — Authentication required

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `error` | string | No | Error message Example: `An error occurred` |

Example:

```json
{
    "success": false,
    "error": "User not found"
}
```


### POST /keys

**Generate a new API key**

Creates a new API key for the authenticated user

**Authentication:** bearerAuth, sessionAuth

**Request Body (optional):**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | Friendly name for the API key Example: `Production API Key` |
| `expires_at` | string(date-time) | No | ISO 8601 timestamp when the key should expire Example: `2026-01-15T00:00:00+00:00` |

**Responses:**

#### ✅ 201 — API key generated successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `message` | string | No | Example: `API key generated successfully` |
| `data` | object | No |  |

#### ❌ 401 — Authentication required

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `error` | string | No | Error message Example: `An error occurred` |

Example:

```json
{
    "success": false,
    "error": "User not found"
}
```


### DELETE /keys/{id}

**Revoke an API key**

Revokes an API key, making it inactive

**Authentication:** bearerAuth, sessionAuth

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string(uuid) | Yes | The ID of the API key to revoke |

**Responses:**

#### ✅ 200 — API key revoked successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `message` | string | No | Example: `API key revoked successfully` |

#### ❌ 401 — Authentication required

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `error` | string | No | Error message Example: `An error occurred` |

Example:

```json
{
    "success": false,
    "error": "User not found"
}
```

#### ❌ 404 — API key not found

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `error` | string | No | Error message Example: `An error occurred` |

Example:

```json
{
    "success": false,
    "error": "API key not found or unauthorized"
}
```


---

*Generated by [CleanDocs](https://cleandocs.dev) — AI-readable API documentation*