@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Convex Management API
@base https://api.convex.dev/v1
@version 1.0.0
@auth Bearer bearer | Bearer bearer | Bearer bearer | Bearer bearer
@endpoints 34
@hint download_for_search
@toc teams(12), projects(8), deployments(10), list_personal_access_tokens(1), create_personal_access_token(1), delete_personal_access_token(1), token_details(1)

@group teams
@endpoint POST /teams/{team_id}/create_project
@desc Create project
@required {team_id: int(int64) # Team ID, projectName: str}
@optional {deploymentClass: str # When creating a deployment, the class to use for the deployment. If not provided, the default deployment class for your team will be used., deploymentRegion: any, deploymentType: any}
@returns(200) {deploymentName: str?, deploymentUrl: str?, projectId: int(int64)}

@endpoint GET /teams/{team_id}/list_projects
@desc List projects
@required {team_id: int(int64) # Team ID}
@returns(200)

@endgroup

@group projects
@endpoint GET /projects/{project_id}/list_deployments
@desc List deployments
@required {project_id: int(int64) # Project ID}
@optional {includeLocal: bool # If true, include local deployments in the response (filtered to only show local deployments created by the requesting team member)., isDefault: bool # If true, only include default deployments. If false, only include non-default deployments., deploymentType: any # Only include deployments of the given deployment type.}
@returns(200)

@endpoint GET /projects/{project_id}/deployment
@desc Get deployment in project by id
@required {project_id: int(int64) # Project ID}
@optional {reference: any # The reference of the deployment to retrieve., defaultProd: bool # If true, retrieve the default production deployment., defaultDev: bool # If true, retrieve the default dev deployment for the calling user.}
@returns(200)

@endgroup

@group teams
@endpoint GET /teams/{team_id_or_slug}/projects/{project_slug}/deployment
@desc Get deployment in project by slug
@required {team_id_or_slug: str # Team ID or slug, project_slug: str # Project slug}
@optional {reference: any # The reference of the deployment to retrieve., defaultProd: bool # If true, retrieve the default production deployment., defaultDev: bool # If true, retrieve the default dev deployment for the calling user.}
@returns(200)

@endgroup

@group projects
@endpoint POST /projects/{project_id}/delete
@desc Delete project
@required {project_id: int(int64) # Project ID}
@returns(200)

@endpoint GET /projects/{project_id}
@desc Get project by ID
@required {project_id: int(int64) # Project ID}
@returns(200) {createTime: int(int64), id: int(int64), name: str, slug: str, teamId: int(int64), teamSlug: str}

@endgroup

@group teams
@endpoint GET /teams/{team_id_or_slug}/projects/{project_slug}
@desc Get project by slug
@required {team_id_or_slug: str # Team ID or slug, project_slug: str # Project slug}
@returns(200) {createTime: int(int64), id: int(int64), name: str, slug: str, teamId: int(int64), teamSlug: str}

@endgroup

@group projects
@endpoint POST /projects/{project_id}/create_deployment
@desc Create deployment
@required {project_id: int(int64) # Project ID, type: str(dev/prod/preview/custom)}
@optional {class: str # The class to use for this deployment. If not provided, the default deployment class for your team will be used., expiresAt: int(int64) # Timestamp in milliseconds when this deployment will be deleted. Preview deployments have this set by default unless overridden. Must be at least 30 minutes in the future and cannot exceed the team’s preview deployment retention days entitlement from now. Set to `null` to clear the expiration., isDefault: bool # When creating a prod deployment, whether the deployment is the default production deployment for the project (i.e. the one used by default when running `npx convex deploy`). When creating a dev deployment, whether the deployment is the default development deployment for the member that creates it (i.e. the one used by default when running `npx convex dev`). This option can’t be set on other types of deployments. If not provided, defaults to `true` when creating a dev or prod deployment without providing a reference (and defaults to `false` otherwise)., reference: str # An identifier that uniquely identifies this deployment within the project. By providing a reference, you can create multiple dev and prod deployments in the project. If you don’t provide a reference, the endpoint will create the default production deployment for the project, or the default development deployment for the member that creates it (i.e. the deployment used by default when running `npx convex deploy` or `npx convex dev` respectively). When not providing a reference, a reference will be automatically generated., region: any}
@returns(200)

@endgroup

@group deployments
@endpoint POST /deployments/{deployment_name}/delete
@desc Delete deployment
@required {deployment_name: any # Deployment Name}
@returns(200)

@endpoint GET /deployments/{deployment_name}
@desc Get deployment
@required {deployment_name: str # Deployment Name}
@returns(200)

@endpoint PATCH /deployments/{deployment_name}
@desc Update deployment
@required {deployment_name: str # Deployment Name}
@optional {dashboardEditConfirmation: bool # Controls whether the dashboard requires a confirmation before allowing edits during a browser session for this deployment. If set to `null`, the setting is reset to the default behavior (true for prod deployments, false for dev and preview deployments). If set to `true` or `false`, the setting is explicitly overridden., expiresAt: int(int64) # Timestamp in milliseconds when this deployment will be deleted. Preview deployments have this set by default unless overridden. Must be at least 30 minutes in the future and cannot exceed the team's preview deployment retention days entitlement from now. Set to `null` to clear the expiration., reference: str # The reference of the deployment. When provided, must match the following rules:   - be unique across deployment references in the project   - 3 to 100 characters (included)   - only lowercase letters, numbers, "-"" and "/"   - not follow the deployment name format [a-z]+-[a-z]+-[0-9]+ (e.g.     "happy-capybara-123")   - not start with "local-""   - not be one of the following reserved keywords: "prod", "dev",     "cloud", "local", "default", "name", "new", "existing",     "deployment", "preview", sendLogsToClient: bool # Whether to send function logs to the client. If set to `null`, the setting is reset to the deployment-type default (true for dev/preview, false for prod). If set to `true` or `false`, the setting is explicitly overridden.}
@returns(200)

@endpoint POST /deployments/{deployment_name}/transfer
@desc Transfer deployment
@required {deployment_name: str # Deployment Name, destinationProjectId: int(int64)}
@returns(204)

@endgroup

@group teams
@endpoint GET /teams/{team_id}/list_deployment_classes
@desc List deployment classes
@required {team_id: any # Team ID}
@returns(200) {items: [map]}

@endpoint GET /teams/{team_id}/list_deployment_regions
@desc List deployment regions
@required {team_id: any # Team ID}
@returns(200) {items: [map]}

@endpoint GET /teams/{team_id}/list_deployments
@desc List deployments for team
@required {team_id: int(int64) # Team ID}
@optional {cursor: str # Cursor for pagination, limit: int(int64) # Max results per page (default: 100, max: 100), sortBy: str # Sort field: createTime, lastDeployTime, reference, sortOrder: str # Sort order: asc, desc, deploymentType: str # Filter by type: dev, prod, preview, custom, q: str # Search by deployment name or reference, projectId: int(int64) # Filter by project ID, creator: int(int64) # Filter by creator member ID, isDefault: bool # Filter by default deployment status}
@returns(200) {items: [any], pagination: map{hasMore: bool, nextCursor: str?}}

@endpoint GET /teams/{team_id}/list_local_deployments
@desc List local deployments
@required {team_id: int(int64) # Team ID}
@returns(200) {items: [any]}

@endgroup

@group deployments
@endpoint POST /deployments/{deployment_name}/create_deploy_key
@desc Create deploy key
@required {deployment_name: any # Deployment name, name: str # Name for the deploy key.}
@returns(200) {deployKey: str}

@endpoint GET /deployments/{deployment_name}/list_deploy_keys
@desc List deploy keys
@required {deployment_name: any # Deployment name}
@returns(200)

@endpoint POST /deployments/{deployment_name}/delete_deploy_key
@desc Delete deploy key
@required {deployment_name: any # Deployment name, id: str # The token to delete. This can be the secret value of the token or the token's unique name.}
@returns(200)

@endgroup

@group projects
@endpoint POST /projects/{project_id}/create_preview_deploy_key
@desc Create preview deploy key
@required {project_id: int(int64) # Project ID, name: str # Name for the preview deploy key.}
@returns(200) {previewDeployKey: str}

@endpoint GET /projects/{project_id}/list_preview_deploy_keys
@desc List preview deploy keys
@required {project_id: int(int64) # Project ID}
@optional {includeManaged: bool # If true, include managed preview deploy keys (e.g., created by external integrations like Vercel) in the response. Defaults to false.}
@returns(200) {items: [map]}

@endpoint POST /projects/{project_id}/delete_preview_deploy_key
@desc Delete preview deploy key
@required {project_id: int(int64) # Project ID, id: str # The token to delete. This can be the secret value of the token or the token's unique name.}
@returns(200)

@endgroup

@group list_personal_access_tokens
@endpoint GET /list_personal_access_tokens
@desc List personal access tokens
@optional {cursor: str # Cursor for pagination, limit: int(int64) # Maximum number of tokens to return (default 10, max 100)}
@returns(200) {items: [map], pagination: map{hasMore: bool, nextCursor: str?}}

@endgroup

@group create_personal_access_token
@endpoint POST /create_personal_access_token
@desc Create personal access token
@required {name: str # Name for the personal access token.}
@returns(200) {accessToken: str}

@endgroup

@group delete_personal_access_token
@endpoint POST /delete_personal_access_token
@desc Delete personal access token
@required {id: str # The token to delete. This can be the secret value of the token or the token's unique name.}
@returns(200)

@endgroup

@group token_details
@endpoint GET /token_details
@desc Get token details
@returns(200)

@endgroup

@group deployments
@endpoint POST /deployments/{deployment_name}/create_custom_domain
@desc Create custom domain
@required {deployment_name: any # Deployment name, domain: str # The custom domain name to delete., requestDestination: str(convexCloud/convexSite)}
@returns(200)

@endpoint POST /deployments/{deployment_name}/delete_custom_domain
@desc Delete custom domain
@required {deployment_name: any # Deployment name, domain: str # The custom domain name to delete., requestDestination: str(convexCloud/convexSite)}
@returns(200)

@endpoint GET /deployments/{deployment_name}/custom_domains
@desc List custom domains
@required {deployment_name: any # Deployment name}
@returns(200) {domains: [map]}

@endgroup

@group teams
@endpoint GET /teams/{team_id}/list_members
@desc List team members
@required {team_id: any # Team ID}
@returns(200) {items: [map]}

@endpoint POST /teams/create_team
@desc Create a team
@required {defaultRegion: str(aws-us-east-1/aws-eu-west-1), name: str}
@returns(201) {creator: any, defaultRegion: any, id: int(int64), managedBy: any, managedByUrl: str?, name: str, referralCode: str, referredBy: any, slug: str, ssoLoginId: str?, suspended: bool} # Team created successfully
@errors {403: Caller is not authorized to create teams}

@endpoint POST /teams/{team_id}/create_access_token
@desc Create a team access token
@required {team_id: any}
@returns(201) {accessToken: str, tokenType: str} # Team access token created successfully
@errors {403: Caller is not authorized to create team access tokens}

@endpoint POST /teams/{team_id}/invite_team_member
@required {team_id: any, email: str, role: str(admin/developer)}
@returns(200)

@endgroup

@end