Deno Revisions API

openapi: 3.1.0
info:
  title: Deno Deploy REST Apps Revisions API
  description: The Deno Deploy REST API (v1) provides programmatic access to manage projects and deployments on the Deno Deploy serverless edge platform. It exposes endpoints for creating and managing organizations, projects, deployments, domains, and KV databases, as well as retrieving analytics and usage metrics. Authentication uses HTTP Bearer tokens generated from the Deno Deploy dashboard. This v1 API is scheduled for sunset on July 20, 2026; users should migrate to the v2 API.
  version: '1.0'
  contact:
    name: Deno Deploy Support
    url: https://deno.com/deploy
  termsOfService: https://deno.com/deploy/terms
servers:
- url: https://api.deno.com/v1
  description: Deno Deploy Production API
security:
- bearerAuth: []
tags:
- name: Revisions
  description: Deploy new revisions, track build progress, cancel builds, and delete revisions. Revisions are immutable snapshots of deployed code.
paths:
  /apps/{app}/deploy:
    post:
      operationId: deployApp
      summary: Create revision
      description: Creates a new revision (deployment) for an application by uploading assets and optional configuration. Assets are key-value pairs where keys are file paths relative to /app/src and values describe file content as UTF-8 text, base64-encoded binary, or symlinks. The revision progresses through queued, building, and succeeded (or failed) states. Build progress can be tracked via the revisions progress endpoint.
      tags:
      - Revisions
      parameters:
      - $ref: '#/components/parameters/app'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployRequest'
      responses:
        '202':
          description: Revision created and build queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Revision'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/{app}/revisions:
    get:
      operationId: listRevisions
      summary: List revisions for app
      description: Returns a cursor-paginated list of all revisions for a specific application, optionally filtered by build status. Results are ordered by creation date descending.
      tags:
      - Revisions
      parameters:
      - $ref: '#/components/parameters/app'
      - name: cursor
        in: query
        description: Opaque pagination cursor from the previous response Link header
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of revisions to return (1-100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
      - name: status
        in: query
        description: Filter revisions by build status
        schema:
          type: string
          enum:
          - skipped
          - queued
          - building
          - succeeded
          - failed
      responses:
        '200':
          description: Revisions listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RevisionListItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /revisions/{revision}:
    get:
      operationId: getRevision
      summary: Get revision details
      description: Retrieves complete details for a specific revision by its globally unique revision ID, including build status, failure reason, labels, layers, environment variables, and runtime configuration.
      tags:
      - Revisions
      parameters:
      - $ref: '#/components/parameters/revision'
      responses:
        '200':
          description: Revision retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Revision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteRevision
      summary: Delete revision
      description: Permanently deletes a specific revision. Revisions that are currently serving production or preview traffic cannot be deleted until the associated app is updated to use a different revision.
      tags:
      - Revisions
      parameters:
      - $ref: '#/components/parameters/revision'
      responses:
        '204':
          description: Revision deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /revisions/{revision}/cancel:
    post:
      operationId: cancelRevision
      summary: Cancel revision build
      description: Requests cancellation of an in-progress revision build. Only revisions in the queued or building state can be cancelled. The revision status transitions to failed upon successful cancellation.
      tags:
      - Revisions
      parameters:
      - $ref: '#/components/parameters/revision'
      responses:
        '200':
          description: Revision build cancellation requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Revision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /revisions/{revision}/progress:
    get:
      operationId: streamRevisionProgress
      summary: Stream revision build progress
      description: Streams real-time build progress for a revision as it moves through the preparing, installing, building, and deploying stages. Returns a Server-Sent Events stream or newline-delimited JSON stream depending on the Accept header. The stream emits message events containing RevisionProgress objects, a done event on completion, and an error event on failure.
      tags:
      - Revisions
      parameters:
      - $ref: '#/components/parameters/revision'
      responses:
        '200':
          description: Build progress stream started
          content:
            text/event-stream:
              schema:
                type: string
                description: 'Server-Sent Events stream. Events: message (RevisionProgress data), done (build complete), error (build failed).'
            application/x-ndjson:
              schema:
                type: string
                description: Newline-delimited JSON stream of RevisionProgress objects
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    EnvVarInputForDeploy:
      type: object
      description: Environment variable input specific to revision deployment
      required:
      - key
      - value
      properties:
        key:
          type: string
          description: Environment variable name
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          maxLength: 128
        value:
          type: string
          description: Environment variable value
          maxLength: 4096
        secret:
          type: boolean
          description: Whether to treat this variable as a secret
          default: false
        contexts:
          description: Contexts in which this variable is active
          oneOf:
          - type: string
            enum:
            - all
          - type: array
            items:
              type: string
    Asset:
      type: object
      description: A file asset included in a deployment. Supports UTF-8 text files, base64-encoded binary files, and symbolic links. File paths are relative to /app/src.
      required:
      - kind
      properties:
        kind:
          type: string
          description: Asset type
          enum:
          - file
          - symlink
        encoding:
          type: string
          description: Content encoding for file assets
          enum:
          - utf-8
          - base64
        content:
          type: string
          description: File content as a UTF-8 string or base64-encoded string
        target:
          type: string
          description: Target path for symlink assets
    DeployRequest:
      type: object
      description: Request body for creating a new revision (deployment)
      required:
      - assets
      properties:
        assets:
          type: object
          description: Map of file paths to asset objects. Keys are paths relative to /app/src (e.g., "main.ts"). Values describe content as UTF-8 text, base64-encoded binary, or symlinks.
          additionalProperties:
            $ref: '#/components/schemas/Asset'
        config:
          $ref: '#/components/schemas/Config'
        layers:
          type: array
          description: Layer references for this revision; overrides app-level layers
          items:
            $ref: '#/components/schemas/LayerRefInput'
        env_vars:
          type: array
          description: Revision-scoped environment variables
          items:
            $ref: '#/components/schemas/EnvVarInputForDeploy'
        labels:
          type: object
          description: Labels to assign to this revision
          additionalProperties:
            type: string
        production:
          type: boolean
          description: Whether to deploy this revision to the production slot
          default: true
        preview:
          type: boolean
          description: Whether to deploy this revision to the preview slot
          default: false
    LayerRefInput:
      type: object
      description: Input for specifying a layer reference when creating or updating an app
      required:
      - id
      properties:
        id:
          type: string
          description: UUID or slug of the layer to reference
    LayerRef:
      type: object
      description: A reference to a configuration layer attached to an app or revision
      required:
      - id
      properties:
        id:
          type: string
          description: UUID or slug of the referenced layer
        slug:
          type: string
          description: Human-readable slug of the layer
    CronJob:
      type: object
      description: A scheduled cron job definition for periodic task execution
      required:
      - name
      - schedule
      - handler
      properties:
        name:
          type: string
          description: Human-readable name for the cron job
        schedule:
          type: string
          description: Cron expression defining the execution schedule
        handler:
          type: string
          description: Function or module path to invoke on each scheduled execution
    Runtime:
      type: object
      description: Runtime configuration for the deployed application
      required:
      - type
      properties:
        type:
          type: string
          description: Runtime execution type
          enum:
          - dynamic
          - static
        entrypoint:
          type: string
          description: Entry point file path for dynamic runtimes, relative to /app/src
        args:
          type: array
          description: Additional arguments passed to the runtime entry point
          items:
            type: string
        cwd:
          type: string
          description: Working directory for the runtime process
        spa:
          type: boolean
          description: Whether to enable single-page application fallback routing for static runtimes (serves index.html for unmatched paths)
    Revision:
      type: object
      description: 'An immutable snapshot of deployed code on Deno Deploy v2. Revisions replace the Deployment concept from v1. Once created, a revision cannot be modified; a new revision must be deployed to make changes. Revisions progress through: queued -> building -> succeeded (or failed/skipped).'
      required:
      - id
      - status
      properties:
        id:
          type: string
          description: Globally unique identifier for the revision
        status:
          type: string
          description: Current build and deployment status
          enum:
          - skipped
          - queued
          - building
          - succeeded
          - failed
        failure_reason:
          type: string
          description: Human-readable reason for failure when status is failed
        labels:
          type: object
          description: Labels assigned to this revision
          additionalProperties:
            type: string
        layers:
          type: array
          description: Layer references active for this revision
          items:
            $ref: '#/components/schemas/LayerRef'
        env_vars:
          type: array
          description: Environment variables set for this revision
          items:
            $ref: '#/components/schemas/EnvVar'
        config:
          $ref: '#/components/schemas/Config'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the revision was created
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the revision was last modified
    Config:
      type: object
      description: Build and runtime configuration for an app or revision. Supports framework-specific presets (Next.js, Astro, Fresh) or custom dynamic/static runtime configurations.
      properties:
        framework:
          type: string
          description: Framework preset to use for build and runtime configuration. Supported values include nextjs, astro, fresh, and others.
        install:
          type: string
          description: Custom install command to run before building
        build:
          type: string
          description: Custom build command
        predeploy:
          type: string
          description: Command to run after build and before deployment
        runtime:
          $ref: '#/components/schemas/Runtime'
        crons:
          type: array
          description: Cron job definitions for scheduled task execution
          items:
            $ref: '#/components/schemas/CronJob'
    Error:
      type: object
      description: Standard error response returned on all API error conditions
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
    RevisionListItem:
      type: object
      description: Summary representation of a revision returned in list responses
      required:
      - id
      - status
      properties:
        id:
          type: string
          description: Globally unique identifier for the revision
        status:
          type: string
          description: Current build status of the revision
          enum:
          - skipped
          - queued
          - building
          - succeeded
          - failed
        failure_reason:
          type: string
          description: Human-readable reason for failure, present only when status is failed
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the revision was created
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the revision was last modified
    EnvVar:
      type: object
      description: An environment variable associated with an app or revision
      required:
      - id
      - key
      properties:
        id:
          type: string
          description: Unique identifier for the environment variable entry
        key:
          type: string
          description: Environment variable name (alphanumeric and underscores, max 128 chars)
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          maxLength: 128
        value:
          type: string
          description: Environment variable value. Omitted for secret variables to prevent accidental exposure.
          maxLength: 4096
        secret:
          type: boolean
          description: Whether the variable is treated as a secret (value is redacted)
        contexts:
          description: Deployment contexts in which this variable is active. Use "all" for all contexts or an array of specific context names.
          oneOf:
          - type: string
            enum:
            - all
          - type: array
            items:
              type: string
  parameters:
    app:
      name: app
      in: path
      required: true
      description: App UUID or human-readable slug
      schema:
        type: string
    revision:
      name: revision
      in: path
      required: true
      description: Globally unique revision ID
      schema:
        type: string
  responses:
    Unauthorized:
      description: Unauthorized - missing or invalid Bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found - the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Generate tokens from the Deno Deploy dashboard under Settings > Access Tokens.
externalDocs:
  description: Deno Deploy REST API Documentation
  url: https://docs.deno.com/deploy/api/rest/