---
title: "Create a deployment"
openapi: "api/radiant.openapi.yaml"
method: "POST"
path: "/v1/deployments"
---

# Create a deployment

POST `/v1/deployments`

Starts a deployment for the API key's site from the latest commit on its configured branch. A newer deployment supersedes any queued or building deployment for the same site. Every accepted build counts toward the site's daily deployment limit, including builds that are later canceled.

OpenAPI spec: https://radiantdocs.com/docs/api/radiant.openapi.yaml

## Header

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `Authorization` | Yes | `string` | A site-scoped key created from the Radiant dashboard. |

## Responses

### 202

The deployment was accepted and dispatched.

Content types: `application/json`

### 401

The request is missing a valid, active Radiant API key.

Content types: `application/json`

### 403

The API key does not have the scope required by the operation.

Content types: `application/json`

### 404

The resource does not exist or is outside the API key's site scope.

Content types: `application/json`

### 409

The site repository or its credentials are not ready for deployment.

Content types: `application/json`

### 429

The site reached its daily deployment limit.

Content types: `application/json`

### 500

Radiant could not complete the request because of an internal error.

Content types: `application/json`

### 502

Radiant could not load the configured repository from GitHub.

Content types: `application/json`

### 503

Radiant created the deployment record but could not dispatch its build.

Content types: `application/json`

## OpenAPI operation

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Radiant API",
    "version": "1.0.0",
    "description": "Trigger Radiant Docs deployments and retrieve their status.",
    "contact": {
      "name": "Radiant Docs Support",
      "url": "https://radiantdocs.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://radiantdocs.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/deployments": {
      "post": {
        "operationId": "createDeployment",
        "summary": "Create a deployment",
        "description": "Starts a deployment for the API key's site from the latest commit on its configured branch. A newer deployment supersedes any queued or building deployment for the same site. Every accepted build counts toward the site's daily deployment limit, including builds that are later canceled.\n",
        "tags": [
          "Deployments"
        ],
        "responses": {
          "202": {
            "description": "The deployment was accepted and dispatched.",
            "headers": {
              "Location": {
                "description": "Relative URL of the deployment status resource.",
                "schema": {
                  "type": "string",
                  "example": "/v1/deployments/90a76b22-8f25-4fc7-95cc-b3a5b2f24108"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Deployment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The site repository or its credentials are not ready for deployment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "The site reached its daily deployment limit.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the daily limit resets at midnight UTC.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "description": "Radiant could not load the configured repository from GitHub.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Radiant created the deployment record but could not dispatch its build.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Deployments",
      "description": "Build and publish a documentation site."
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Radiant API key",
        "description": "A site-scoped key created from the Radiant dashboard."
      }
    },
    "schemas": {
      "Deployment": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "siteId",
          "status",
          "trigger",
          "commit",
          "failure",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "90a76b22-8f25-4fc7-95cc-b3a5b2f24108"
          },
          "siteId": {
            "type": "string",
            "format": "uuid",
            "example": "25853bf0-7640-45c6-b008-568c6d90d8f8"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "building",
              "success",
              "failed",
              "canceled"
            ],
            "example": "building"
          },
          "trigger": {
            "type": "string",
            "description": "The workflow that created the deployment.",
            "example": "api"
          },
          "commit": {
            "$ref": "#/components/schemas/Commit"
          },
          "failure": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DeploymentFailure"
              },
              {
                "type": "null"
              }
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-01T18:30:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-01T18:30:06.000Z"
          }
        }
      },
      "Commit": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sha",
          "message"
        ],
        "properties": {
          "sha": {
            "type": "string",
            "example": "4f91d8616e87bb258320565ff3eeca7c1f5f260b"
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "example": "Update authentication documentation"
          }
        }
      },
      "DeploymentFailure": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "example": "The docs configuration is invalid."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "not_found"
              },
              "message": {
                "type": "string",
                "example": "Deployment not found."
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The request is missing a valid, active Radiant API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key does not have the scope required by the operation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource does not exist or is outside the API key's site scope.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "InternalError": {
        "description": "Radiant could not complete the request because of an internal error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}
```