API endpoint reference

Default content

{
  "group": "Deployments",
  "method": "POST",
  "path": "/v1/deployments",
  "baseUrl": "https://api.rivetlane.dev",
  "title": "Create a deployment",
  "description": "Builds a commit of a linked project and deploys it to a preview or to production. Returns immediately with `status: building`; the deployment moves to `ready` or `failed` when the build ends. A newer deployment to the same branch cancels an older one that is still building.",
  "auth": "Requires a token with the `deployments:write` scope in `Authorization: Bearer`. Limited to 60 requests per minute per project.",
  "labels": {
    "name": "Parameter",
    "required": "Required",
    "optional": "Optional",
    "description": "Description",
    "request": "Request",
    "response": "Response",
    "copy": "Copy",
    "copied": "Copied"
  },
  "paramGroups": [
    {
      "title": "Body parameters",
      "params": [
        {
          "name": "project",
          "type": "string",
          "required": true,
          "description": "Project name or ID, as in `[project] name` of `rivetlane.toml`."
        },
        {
          "name": "branch",
          "type": "string",
          "required": true,
          "description": "Git branch to build. The latest commit is used unless `commit` is set."
        },
        {
          "name": "target",
          "type": "enum",
          "required": false,
          "description": "Where the deployment receives traffic once it is ready.",
          "detail": "`preview` (default) · `production`"
        },
        {
          "name": "commit",
          "type": "string",
          "required": false,
          "description": "Full or short SHA to build instead of the branch head."
        },
        {
          "name": "force",
          "type": "boolean",
          "required": false,
          "description": "Skip the build cache. Needed after changing a `PUBLIC_` variable.",
          "detail": "Default: `false`"
        },
        {
          "name": "meta",
          "type": "object",
          "required": false,
          "description": "Up to 16 string pairs stored with the deployment and returned in webhooks."
        }
      ]
    },
    {
      "title": "Headers",
      "params": [
        {
          "name": "Idempotency-Key",
          "type": "string",
          "required": false,
          "description": "Retries with the same key within 24 hours return the original deployment."
        }
      ]
    }
  ],
  "requests": [
    {
      "label": "curl",
      "language": "shell",
      "code": "$ curl https://api.rivetlane.dev/v1/deployments \\\n    -H \"Authorization: Bearer $RIVET_TOKEN\" \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\n      \"project\": \"storefront\",\n      \"branch\": \"main\",\n      \"target\": \"production\"\n    }'"
    },
    {
      "label": "Node",
      "language": "ts",
      "code": "const deployment = await rivet.deployments.create({\n  project: \"storefront\",\n  branch: \"main\",\n  target: \"production\",\n})"
    },
    {
      "label": "Python",
      "language": "python",
      "code": "deployment = rivet.deployments.create(\n    project=\"storefront\",\n    branch=\"main\",\n    target=\"production\",\n)"
    }
  ],
  "responses": [
    {
      "status": 201,
      "text": "Created",
      "body": "{\n  \"id\": \"dpl_7Hq2xKfR\",\n  \"project\": \"storefront\",\n  \"branch\": \"main\",\n  \"commit\": \"a41c9e2\",\n  \"target\": \"production\",\n  \"status\": \"building\",\n  \"url\": \"https://storefront-a41c9e2.rivetlane.app\",\n  \"created_at\": \"2026-10-09T14:02:11Z\"\n}"
    },
    {
      "status": 404,
      "text": "Not found",
      "body": "{\n  \"error\": {\n    \"code\": \"branch_not_found\",\n    \"message\": \"Branch 'mian' does not exist in quillon/storefront.\",\n    \"param\": \"branch\"\n  }\n}"
    },
    {
      "status": 422,
      "text": "Unprocessable",
      "body": "{\n  \"error\": {\n    \"code\": \"secret_in_config\",\n    \"message\": \"rivetlane.toml defines a credential-like key: TALLYBIRD_SECRET_KEY.\",\n    \"doc_url\": \"https://rivetlane.dev/docs/env#defaults-in-rivetlane-toml\"\n  }\n}"
    },
    {
      "status": 429,
      "text": "Rate limited",
      "body": "{\n  \"error\": {\n    \"code\": \"rate_limited\",\n    \"message\": \"60 requests per minute per project. Retry after 12s.\",\n    \"retry_after\": 12\n  }\n}"
    }
  ]
}