Skip to main content

Platform APIs

info

Convex Platform APIs are in openly available in Beta. Please contact platforms@convex.dev if your use case requires additional capabilities.

This guide is for products that want to orchestrate multiple Convex projects in their accounts or manage projects in their users' accounts. These APIs are most often used by AI app builders, such as Bloom or A0.

These guides assume a good understanding of Convex cloud hierarchy (teams, projects, and deployments) as well as the development workflow.

Managing your own projects

This means that you are creating projects, deployments, and pushing code programmatically in the context of the team you own.

To manage projects in your own team, you need to get a team-scoped token and ID from your Team Settings.

caution

These tokens are owned by the team member that's logged into the Convex dashboard when you retrieve them.

This means that this user owns any dev deployments created by using these tokens. If this user leaves the team, that also deletes all of their dev deployments from the team.

We recommend creating a separate service account that's added as a team member. Retrieve the token after logging in as this service account.

Managing your users' projects

This means your users authorize your product to manage their own Convex team or projects.

To do this, you need to create an OAuth 2.0 application so that the user can grant your product the necessary permissions.

Follow the OAuth Applications guide to create an OAuth application and request a relevant token.

APIs to manage projects

Once you have obtained a token from one of the methods above, you can use it to call the relevant APIs to manage Convex projects and deployments.

Management API Reference

Pushing code to a deployment

Working with your deployment should be scripted primarily with the existing Convex CLI. The Convex CLI manages a lot of the heavy lifting such as bundling code properly handling responses etc.

The examples here assume you are working in a container with shell and file system access from which you can drive the app building process. You likely already have this if you're generating frontend code.

A CONVEX_DEPLOY_KEY is the value returned by the Create deploy key API.

Pushing code to the dev Convex backend

CONVEX_DEPLOY_KEY="YOUR_DEPLOY_KEY" npx convex dev --once

Pushing code to the prod Convex backend

CONVEX_DEPLOY_KEY="YOUR_DEPLOY_KEY" npx convex deploy

To view the full list of commands, refer to the CLI documentation.