Platform APIs
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.
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.
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: 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.
Set 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.