Convex Projects API

openapi: 3.1.0
info:
  title: Convex Deployment Platform AccessTokens Projects API
  description: The Convex Deployment Platform API is a deployment-scoped administrative REST API for configuring individual Convex deployments. It exposes private endpoints accessible only to deployment administrators and supports operations such as managing environment variables and other deployment configuration settings. Each deployment has its own endpoint in the format https://{deployment-name}.convex.cloud/api/v1/. Authentication requires an Authorization header using deployment keys, Team Access Tokens, or OAuth Application Tokens formatted as "Convex {token}". This API is currently in Beta and is intended for platform integrations and infrastructure automation workflows.
  version: v1-beta
  contact:
    name: Convex Platform Support
    email: platforms@convex.dev
    url: https://www.convex.dev/community
  termsOfService: https://www.convex.dev/terms
servers:
- url: https://{deploymentName}.convex.cloud/api/v1
  description: Convex Deployment Server
  variables:
    deploymentName:
      default: happy-otter-123
      description: The deployment name found in the Convex dashboard or via the Management API. Each deployment has a unique subdomain under convex.cloud.
security:
- convexAuth: []
tags:
- name: Projects
  description: Create, list, retrieve, and delete Convex projects within a team. Projects group deployments and serve as the top-level organizational unit for Convex applications.
paths:
  /teams/{team_id}/create_project:
    post:
      operationId: createProject
      summary: Create a new project
      description: Provisions a new Convex project within the specified team. Optionally creates an initial production deployment in the specified cloud region and deployment class. Returns the new project's ID and slug along with details of any provisioned deployment.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/teamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Bad request — invalid parameters
        '401':
          description: Unauthorized — missing or invalid token
  /teams/{team_id}/list_projects:
    get:
      operationId: listProjects
      summary: List projects in a team
      description: Returns all Convex projects belonging to the specified team. Each project entry includes its ID, slug, name, and associated deployment information. Useful for enumerating resources available to the authenticated token holder.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/teamId'
      responses:
        '200':
          description: Projects listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized — missing or invalid token
  /projects/{project_id}:
    get:
      operationId: getProject
      summary: Get a project by ID
      description: Retrieves details for a specific Convex project identified by its integer project ID. Returns the project's name, slug, team association, and deployment summary.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Project retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Project not found
  /teams/{team_id_or_slug}/projects/{project_slug}:
    get:
      operationId: getProjectBySlug
      summary: Get a project by team and project slug
      description: Retrieves a project by its human-readable slug within a team identified by either team ID or team slug. This is useful when project identifiers are stored as slugs rather than integer IDs.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/teamIdOrSlug'
      - $ref: '#/components/parameters/projectSlug'
      responses:
        '200':
          description: Project retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Project not found
  /projects/{project_id}/delete:
    post:
      operationId: deleteProject
      summary: Delete a project
      description: Permanently deletes a Convex project and all associated deployments. This operation is irreversible. All deployments within the project are also deleted, and all associated resources (functions, data, files) are permanently removed.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Project deleted successfully
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Project not found
components:
  parameters:
    teamIdOrSlug:
      name: team_id_or_slug
      in: path
      required: true
      description: Either the integer team ID or the human-readable team slug.
      schema:
        type: string
    projectId:
      name: project_id
      in: path
      required: true
      description: The integer identifier of the Convex project. Obtainable via the List Projects endpoint or assigned during project creation.
      schema:
        type: integer
        format: int64
    projectSlug:
      name: project_slug
      in: path
      required: true
      description: The human-readable slug of the project within the team.
      schema:
        type: string
    teamId:
      name: team_id
      in: path
      required: true
      description: The integer identifier of the Convex team. Available in the Convex dashboard when creating Team Access Tokens.
      schema:
        type: integer
        format: int64
  schemas:
    CreateProjectRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Display name for the new project.
        team_id:
          type: integer
          format: int64
          description: ID of the team to create the project in.
        deployment_region:
          type: string
          description: Cloud region for the initial production deployment. If omitted, no initial deployment is created.
          enum:
          - aws-us-east-1
          - aws-eu-west-1
        deployment_class:
          type: string
          description: Compute class for the initial production deployment.
          enum:
          - s16
          - s256
          - d1024
    Project:
      type: object
      required:
      - id
      - slug
      - name
      - team_id
      properties:
        id:
          type: integer
          format: int64
          description: Unique integer identifier for the project.
        slug:
          type: string
          description: Human-readable URL-safe identifier for the project within the team.
        name:
          type: string
          description: Display name of the project.
        team_id:
          type: integer
          format: int64
          description: ID of the team that owns this project.
  securitySchemes:
    convexAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authorization header using a deployment key, Team Access Token, or OAuth Application Token. The token must be prefixed with the string "Convex " (e.g. "Authorization: Convex prod:abc123..."). Deployment keys are created in the dashboard or via the Management API.'
externalDocs:
  description: Convex Deployment Platform API Documentation
  url: https://docs.convex.dev/deployment-platform-api