Render Deploys API

openapi: 3.2.0
info:
  title: Render Public Audit Logs Deploys API
  description: Manage everything about your Render services
  version: 1.0.0
  contact:
    name: Render API
    url: https://community.render.com
    email: support@render.com
servers:
- url: https://api.render.com/v1
security:
- BearerAuth: []
tags:
- name: Deploys
  description: '[Deploys](https://render.com/docs/deploys) are the process of updating your service with new code or configuration.

    These endpoints allow you to retrieve data on the deploys of your services

    as well as trigger new deploys and rollbacks. Most changes to your service

    will require a new deploy to take effect.


    To create and manage services, use the `Services` endpoints.

    '
paths:
  /services/{serviceId}/deploys:
    parameters:
    - $ref: '#/components/parameters/serviceIdParam'
    get:
      summary: List deploys
      description: 'List deploys matching the provided filters. If no filters are provided, all deploys for the service are returned.

        '
      operationId: list-deploys
      tags:
      - Deploys
      parameters:
      - name: status
        in: query
        schema:
          type: array
          items:
            $ref: '#/components/schemas/deployStatus'
        required: false
        description: Filter for deploys with the specified statuses
      - name: createdBefore
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Filter for deploys created before a certain time (specified as an ISO 8601 timestamp)
        example: '2021-06-17T08:15:30Z'
      - name: createdAfter
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Filter for deploys created after a certain time (specified as an ISO 8601 timestamp)
        example: '2021-02-17T08:15:30Z'
      - name: updatedBefore
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Filter for deploys updated before a certain time (specified as an ISO 8601 timestamp)
        example: '2021-06-17T08:15:30Z'
      - name: updatedAfter
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Filter for deploys updated after a certain time (specified as an ISO 8601 timestamp)
        example: '2021-02-17T08:15:30Z'
      - name: finishedBefore
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Filter for deploys finished before a certain time (specified as an ISO 8601 timestamp)
        example: '2021-06-17T08:15:30Z'
      - name: finishedAfter
        in: query
        schema:
          type: string
          format: date-time
        required: false
        description: Filter for deploys finished after a certain time (specified as an ISO 8601 timestamp)
        example: '2021-02-17T08:15:30Z'
      - $ref: '#/components/parameters/cursorParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deployList'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '406':
          $ref: '#/components/responses/406NotAcceptable'
        '410':
          $ref: '#/components/responses/410Gone'
        '429':
          $ref: '#/components/responses/429RateLimit'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
    post:
      summary: Trigger deploy
      description: 'Trigger a deploy for the service with the provided ID.

        '
      operationId: create-deploy
      tags:
      - Deploys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clearCache:
                  type: string
                  enum:
                  - clear
                  - do_not_clear
                  default: do_not_clear
                  description: If `clear`, Render clears the service's build cache before deploying. This can be useful if you're experiencing issues with your build.
                commitId:
                  type: string
                  description: 'The SHA of a specific Git commit to deploy for a service. Defaults to the latest commit on the service''s connected branch.


                    Note that deploying a specific commit with this endpoint does not disable autodeploys for the service.


                    You can toggle autodeploys for your service with the [Update service](https://api-docs.render.com/reference/update-service) endpoint or in the Render Dashboard.


                    Not supported for cron jobs.

                    '
                imageUrl:
                  type: string
                  description: 'The URL of the image to deploy for an image-backed service.


                    The host, repository, and image name all must match the currently configured image for the service.

                    '
                deployMode:
                  $ref: '#/components/schemas/DeployMode'
                  description: 'Deployment mode controlling build and deploy behavior.


                    Defaults to `build_and_deploy` when not specified.


                    **Validation:** `deploy_mode` cannot be combined with `commitId` or `imageUrl` or `clearCache`.

                    '
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deploy'
        '202':
          description: Queued
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '406':
          $ref: '#/components/responses/406NotAcceptable'
        '409':
          $ref: '#/components/responses/409Conflict'
        '410':
          $ref: '#/components/responses/410Gone'
        '429':
          $ref: '#/components/responses/429RateLimit'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
  /services/{serviceId}/deploys/{deployId}:
    parameters:
    - $ref: '#/components/parameters/serviceIdParam'
    - $ref: '#/components/parameters/deployIdParam'
    get:
      summary: Retrieve deploy
      description: 'Retrieve the details of a particular deploy for a particular service.

        '
      operationId: retrieve-deploy
      tags:
      - Deploys
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deploy'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '406':
          $ref: '#/components/responses/406NotAcceptable'
        '410':
          $ref: '#/components/responses/410Gone'
        '429':
          $ref: '#/components/responses/429RateLimit'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
  /services/{serviceId}/deploys/{deployId}/cancel:
    parameters:
    - $ref: '#/components/parameters/serviceIdParam'
    - $ref: '#/components/parameters/deployIdParam'
    post:
      summary: Cancel deploy
      description: 'Cancel an in-progress deploy for a service.


        Not supported for cron jobs.

        '
      operationId: cancel-deploy
      tags:
      - Deploys
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deploy'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429RateLimit'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
  /services/{serviceId}/rollback:
    parameters:
    - $ref: '#/components/parameters/serviceIdParam'
    post:
      summary: Roll back deploy
      description: 'Trigger a rollback to a previous deploy of the specified service.


        Triggering a rollback with this endpoint does not disable autodeploys for the service. This means an autodeploy might restore changes you had intentionally rolled back.


        You can toggle autodeploys for your service with the [Update service](https://api-docs.render.com/reference/update-service) endpoint or in the Render Dashboard.

        '
      operationId: rollback-deploy
      tags:
      - Deploys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - deployId
              properties:
                deployId:
                  type: string
                  description: The ID of the deploy to roll back to
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deploy'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429RateLimit'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
components:
  responses:
    406NotAcceptable:
      description: Unable to generate preferred media types as specified by Accept request header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    503ServiceUnavailable:
      description: Server currently unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    410Gone:
      description: The requested resource is no longer available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    409Conflict:
      description: The current state of the resource conflicts with this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    404NotFound:
      description: Unable to find the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    401Unauthorized:
      description: Authorization information is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    429RateLimit:
      description: Rate limit has been surpassed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    500InternalServerError:
      description: An unexpected server error has occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    403Forbidden:
      description: You do not have permissions for the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    400BadRequest:
      description: The request could not be understood by the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  parameters:
    limitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return. For details, see [Pagination](https://api-docs.render.com/reference/pagination).
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
        description: Defaults to 20
    deployIdParam:
      name: deployId
      in: path
      required: true
      description: The ID of the deploy
      schema:
        type: string
    cursorParam:
      name: cursor
      in: query
      required: false
      description: The position in the result list to start from when fetching paginated results. For details, see [Pagination](https://api-docs.render.com/reference/pagination).
      schema:
        type: string
    serviceIdParam:
      name: serviceId
      in: path
      required: true
      description: The ID of the service
      schema:
        type: string
  schemas:
    cursor:
      type: string
    DeployMode:
      type: string
      enum:
      - deploy_only
      - build_and_deploy
      description: 'Controls deployment behavior when triggering a deploy.


        - `deploy_only`: Deploy the last successful build without rebuilding (minimizes downtime)

        - `build_and_deploy`: Build new code and deploy it (default behavior when not specified)


        **Note:** `deploy_only` cannot be combined with `commitId`, `imageUrl` or `clearCache` parameters,

        as those are build related fields.

        '
      default: build_and_deploy
    deploy:
      type: object
      required:
      - id
      properties:
        id:
          type: string
        commit:
          type: object
          properties:
            id:
              type: string
            message:
              type: string
            createdAt:
              type: string
              format: date-time
        image:
          description: Image information used when creating the deploy. Not present for Git-backed deploys
          type: object
          properties:
            ref:
              description: Image reference used when creating the deploy
              type: string
            sha:
              description: SHA that the image reference was resolved to when creating the deploy
              type: string
            registryCredential:
              description: Name of credential used to pull the image, if provided
              type: string
        status:
          $ref: '#/components/schemas/deployStatus'
        trigger:
          type: string
          enum:
          - api
          - blueprint_sync
          - deploy_hook
          - deployed_by_render
          - manual
          - other
          - new_commit
          - rollback
          - service_resumed
          - service_updated
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    error:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
    deployStatus:
      type: string
      enum:
      - created
      - queued
      - build_in_progress
      - update_in_progress
      - live
      - deactivated
      - build_failed
      - update_failed
      - canceled
      - pre_deploy_in_progress
      - pre_deploy_failed
    deployList:
      type: array
      items:
        $ref: '#/components/schemas/deployWithCursor'
    deployWithCursor:
      type: object
      properties:
        deploy:
          $ref: '#/components/schemas/deploy'
        cursor:
          $ref: '#/components/schemas/cursor'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-readme:
  metrics-enabled: false