Convex Projects API

openapi: 3.2.0
info:
  title: Convex Management Projects API
  description: 'The Convex Management API is a REST API for provisioning and managing Convex projects, deployments, teams, and access credentials programmatically. It enables developers and platform integrations to create projects, manage deployments across cloud regions, configure custom domains, and handle team membership without using the Convex dashboard. The API supports two token types: Team Access Tokens (for managing your own team''s resources) and OAuth Application Tokens (for third-party integrations acting on behalf of users). A JavaScript client wrapper is available via the @convex-dev/platform npm package. The API is currently in Beta.'
  version: v1
  contact:
    name: Convex Platform Support
    email: platforms@convex.dev
    url: https://www.convex.dev/community
  termsOfService: https://www.convex.dev/terms
servers:
- url: https://api.convex.dev/v1
  description: Convex Management API Production Server
security:
- teamToken: []
- oauthTeamToken: []
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:
    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
    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
    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:
    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.
    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
  securitySchemes:
    teamToken:
      type: http
      scheme: bearer
      description: Team Access Token created in the Convex dashboard team settings. Grants management access to all projects and deployments within the team.
    oauthTeamToken:
      type: http
      scheme: bearer
      description: OAuth Application Token issued by Convex for third-party integrations acting on behalf of a user's team. Obtained via the Convex OAuth flow.
    oauthProjectToken:
      type: http
      scheme: bearer
      description: OAuth Application Token scoped to a specific project, issued by Convex for third-party integrations.
externalDocs:
  description: Convex Management API Documentation
  url: https://docs.convex.dev/management-api