openapi: 3.1.0
info:
  title: env0 API
  version: "1.0.0"
  description: >-
    REST API for the env0 infrastructure-as-code automation platform. Provides
    programmatic access to organizations, projects, environments, deployments,
    templates, modules, agents, configuration variables, credentials, RBAC,
    approval policies, and VCS provider mappings. Rate limited to 1,000
    requests per 60 seconds. Best-effort spec derived from publicly documented
    surfaces; not exhaustive.
  contact:
    name: env0 Support
    url: https://docs.envzero.com/
  license:
    name: Proprietary
servers:
  - url: https://api.env0.com
    description: env0 API production base URL
security:
  - basicAuth: []
tags:
  - name: Users
  - name: Organizations
  - name: Projects
  - name: Environments
  - name: Deployments
  - name: Templates
  - name: Modules
  - name: Agents
  - name: Configuration
  - name: ApprovalPolicies
  - name: Webhooks
paths:
  /users/me/vcs-provider-user-mappings:
    get:
      tags: [Users]
      summary: Get current user's VCS provider account mappings
      operationId: getUserVcsProviderMappings
      responses:
        "200":
          description: List of VCS provider user mappings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    providerType:
                      type: string
                    providerUserId:
                      type: string
                    providerUserName:
                      type: string
  /organizations:
    get:
      tags: [Organizations]
      summary: List organizations the user belongs to
      operationId: listOrganizations
      responses:
        "200":
          description: Organizations list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Organization"
  /projects:
    get:
      tags: [Projects]
      summary: List projects in an organization
      operationId: listProjects
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Projects list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Project"
    post:
      tags: [Projects]
      summary: Create a new project
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Project"
      responses:
        "201":
          description: Project created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
  /projects/{projectId}:
    parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
    get:
      tags: [Projects]
      summary: Get a project
      operationId: getProject
      responses:
        "200":
          description: Project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
    put:
      tags: [Projects]
      summary: Update a project
      operationId: updateProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Project"
      responses:
        "200":
          description: Updated project
    delete:
      tags: [Projects]
      summary: Delete a project
      operationId: deleteProject
      responses:
        "204":
          description: Project deleted
  /environments:
    get:
      tags: [Environments]
      summary: List environments
      operationId: listEnvironments
      parameters:
        - in: query
          name: projectId
          schema:
            type: string
      responses:
        "200":
          description: Environments list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Environment"
    post:
      tags: [Environments]
      summary: Create an environment and trigger deployment
      operationId: createEnvironment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Environment"
      responses:
        "201":
          description: Environment created
  /environments/{environmentId}:
    parameters:
      - in: path
        name: environmentId
        required: true
        schema:
          type: string
    get:
      tags: [Environments]
      summary: Get an environment
      operationId: getEnvironment
      responses:
        "200":
          description: Environment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Environment"
    delete:
      tags: [Environments]
      summary: Destroy and delete an environment
      operationId: destroyEnvironment
      responses:
        "204":
          description: Environment scheduled for destruction
  /environments/{environmentId}/deployments:
    parameters:
      - in: path
        name: environmentId
        required: true
        schema:
          type: string
    post:
      tags: [Deployments]
      summary: Trigger a deployment on an environment
      operationId: deployEnvironment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                blueprintRevision:
                  type: string
                userRequiresApproval:
                  type: boolean
      responses:
        "201":
          description: Deployment triggered
  /environments/{environmentId}/deployments/{deploymentId}:
    parameters:
      - in: path
        name: environmentId
        required: true
        schema:
          type: string
      - in: path
        name: deploymentId
        required: true
        schema:
          type: string
    get:
      tags: [Deployments]
      summary: Get a deployment log
      operationId: getDeployment
      responses:
        "200":
          description: Deployment
  /templates:
    get:
      tags: [Templates]
      summary: List IaC templates
      operationId: listTemplates
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Templates list
    post:
      tags: [Templates]
      summary: Create a new template
      operationId: createTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Template created
  /modules:
    get:
      tags: [Modules]
      summary: List private modules
      operationId: listModules
      responses:
        "200":
          description: Modules list
  /agents:
    get:
      tags: [Agents]
      summary: List self-hosted agents
      operationId: listAgents
      responses:
        "200":
          description: Agents list
  /configuration:
    get:
      tags: [Configuration]
      summary: List configuration variables
      operationId: listConfigurationVariables
      parameters:
        - in: query
          name: organizationId
          schema:
            type: string
        - in: query
          name: projectId
          schema:
            type: string
        - in: query
          name: environmentId
          schema:
            type: string
      responses:
        "200":
          description: Configuration variables list
    post:
      tags: [Configuration]
      summary: Create or update a configuration variable
      operationId: upsertConfigurationVariable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                value:
                  type: string
                isSensitive:
                  type: boolean
                scope:
                  type: string
                  enum: [GLOBAL, ORGANIZATION, PROJECT, ENVIRONMENT, BLUEPRINT, DEPLOYMENT]
      responses:
        "200":
          description: Variable upserted
  /approval-policies:
    get:
      tags: [ApprovalPolicies]
      summary: List approval policies
      operationId: listApprovalPolicies
      responses:
        "200":
          description: Approval policies list
  /webhooks:
    get:
      tags: [Webhooks]
      summary: List webhook subscriptions
      operationId: listWebhooks
      responses:
        "200":
          description: Webhooks list
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication. Username is the env0 API Key ID and the
        password is the API Key Secret, both created in the env0 organization
        settings.
  schemas:
    Organization:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
    Project:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
    Environment:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        projectId:
          type: string
        status:
          type: string
        blueprintId:
          type: string
        latestDeploymentLogId:
          type: string