API Reference

Complete reference for BeatConnect’s SDK APIs.

Base URL

https://api.beatconnect.com/functions/v1

Authentication

Most endpoints require a JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Get your token from the Creator Portal or via Supabase Auth.

Builds API

Trigger Build

POST /builds

Start a new build for a project.

Headers:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Request Body:

{
  "project_id": "uuid",
  "platforms": ["macos", "windows"],
  "formats": ["vst3", "au"],
  "release_type": "patch",
  "flags": {
    "enableActivationKeys": true,
    "enableCreatorMode": false,
    "enableDebugMode": false
  }
}

Field	Type	Required	Description
`project_id`	string	Yes	Project UUID
`project_version_id`	string	No	Specific version (builder projects)
`platforms`	string[]	No	`["macos", "windows"]`
`formats`	string[]	No	`["vst3", "au", "standalone"]`
`release_type`	string	No	`major`, `minor`, `patch`, `dev`, `release`
`flags`	object	No	Build configuration flags
`clean_build`	boolean	No	Force clean build (no cache)

Response (201):

{
  "id": "build-uuid",
  "project_id": "project-uuid",
  "status": "pending",
  "version_number": "1.0.1",
  "build_number": 5,
  "platforms": ["macos", "windows"],
  "formats": ["vst3", "au"],
  "queued_at": "2025-01-15T10:30:00Z"
}

Get Build Status

GET /builds/:id

Get current status and details of a build.

Response (200):

{
  "id": "build-uuid",
  "project_id": "project-uuid",
  "status": "running",
  "version_number": "1.0.1",
  "build_number": 5,
  "platforms": ["macos", "windows"],
  "formats": ["vst3", "au"],
  "metadata": {
    "current_step": "building",
    "step_progress": 45
  },
  "queued_at": "2025-01-15T10:30:00Z",
  "started_at": "2025-01-15T10:30:15Z",
  "github_run_url": "https://github.com/..."
}

Status Values:

pending — Created, waiting to queue
queued — Waiting for build runner
running — Build in progress
success — Completed successfully
failed — Build failed
cancelled — Manually cancelled

List Builds

GET /builds

List builds for a project.

Query Parameters:

Param	Type	Description
`project_id`	string	Filter by project
`status`	string	Filter by status
`limit`	number	Max results (default: 20)
`offset`	number	Pagination offset

Response (200):

{
  "builds": [
    {
      "id": "build-uuid",
      "project_id": "project-uuid",
      "status": "success",
      "version_number": "1.0.1",
      "completed_at": "2025-01-15T10:35:00Z"
    }
  ],
  "total": 25,
  "limit": 20,
  "offset": 0
}

Get Build Artifacts

GET /builds/:id/artifacts

List artifacts for a completed build.

Response (200):

{
  "artifacts": [
    {
      "id": "artifact-uuid",
      "platform": "macos",
      "format": "vst3",
      "file_name": "MyPlugin.vst3",
      "file_size": 5242880,
      "checksum_sha256": "abc123...",
      "is_signed": true,
      "download_count": 15,
      "created_at": "2025-01-15T10:35:00Z"
    }
  ]
}

Download Artifact

GET /builds/:buildId/download/:artifactId

Get a presigned download URL for an artifact.

Response (200):

{
  "url": "https://r2.beatconnect.com/...",
  "expires_at": "2025-01-15T11:35:00Z"
}

Or redirect (302): Redirects directly to the download URL.

Cancel Build

POST /builds/:id/cancel

Cancel a pending or running build.

Response (200):

{
  "id": "build-uuid",
  "status": "cancelled"
}

Get Build Usage

GET /builds/usage

Get current build quota usage.

Response (200):

{
  "period": "2025-01",
  "used": 3,
  "limit": 5,
  "remaining": 2,
  "extra_builds": 0,
  "reset_at": "2025-02-01T00:00:00Z"
}

Plugin Activation API

Activate

POST /plugin-activation/activate

Activate a license on a machine.

Request Body:

{
  "code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "machine_id": "unique-machine-identifier"
}

Response (200):

{
  "success": true,
  "activations": 1,
  "max_activations": 2,
  "remaining": 1
}

Errors:

Status	Code	Description
400	`invalid_code`	Code format invalid
404	`code_not_found`	Code doesn’t exist
403	`code_revoked`	License was revoked
403	`max_activations_reached`	No slots available

Deactivate

POST /plugin-activation/deactivate

Remove activation from a machine.

Request Body:

{
  "code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "machine_id": "unique-machine-identifier"
}

Response (200):

{
  "success": true,
  "activations": 0,
  "max_activations": 2,
  "message": "Machine deactivated successfully"
}

Validate

POST /plugin-activation/validate

Check if a license is valid on this machine.

Request Body:

{
  "code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "machine_id": "unique-machine-identifier"
}

Response (200):

{
  "valid": true
}

Or:

{
  "valid": false,
  "reason": "not_activated"
}

Reasons:

not_activated — Machine not activated
code_revoked — License revoked
code_not_found — Code doesn’t exist
deactivated — Was deactivated

Get Status

GET /plugin-activation/status/:code

Get public status of a license (no auth required).

Response (200):

{
  "activations": 1,
  "max_activations": 2,
  "available": 1,
  "is_revoked": false
}

Generate Key

POST /plugin-activation/generate

Generate a test activation key.

Headers:

Authorization: Bearer YOUR_TOKEN

Request Body:

{
  "project_id": "project-uuid",
  "max_activations": 2,
  "notes": "Beta tester - John"
}

Response (201):

{
  "code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key_type": "project_test",
  "max_activations": 2,
  "created_at": "2025-01-15T10:30:00Z"
}

List Project Keys

GET /plugin-activation/project/:projectId/keys

List all activation keys for a project.

Headers:

Authorization: Bearer YOUR_TOKEN

Response (200):

{
  "keys": [
    {
      "code": "a1b2c3d4-...",
      "key_type": "project_test",
      "max_activations": 2,
      "current_activations": 1,
      "is_revoked": false,
      "notes": "Beta tester",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

GitHub Integration API

Get Connection Status

GET /github-app-callback/status

Check if GitHub is connected.

Headers:

Authorization: Bearer YOUR_TOKEN

Response (200):

{
  "connected": true,
  "account_login": "your-username",
  "account_type": "User",
  "connected_at": "2025-01-15T10:30:00Z"
}

Disconnect

DELETE /github-app-callback/disconnect

Remove GitHub connection.

Headers:

Authorization: Bearer YOUR_TOKEN

Response (200):

{
  "success": true,
  "message": "GitHub disconnected"
}

Plugin Repositories API

Discover Repos

GET /plugin-repos/discover

List discoverable plugin repositories.

Headers:

Authorization: Bearer YOUR_TOKEN

Response (200):

{
  "repos": [
    {
      "name": "my-plugin",
      "full_name": "username/my-plugin",
      "description": "My awesome plugin",
      "html_url": "https://github.com/username/my-plugin",
      "topics": ["beatconnect-plugin"],
      "default_branch": "main"
    }
  ]
}

Link Repository

POST /plugin-repos/link

Link a repository to a project.

Request Body:

{
  "project_id": "project-uuid",
  "repo_full_name": "username/my-plugin",
  "branch": "main"
}

Response (200):

{
  "success": true,
  "project_id": "project-uuid",
  "source_repo_url": "https://github.com/username/my-plugin"
}

Unlink Repository

POST /plugin-repos/unlink

Remove repository link from a project.

Request Body:

{
  "project_id": "project-uuid"
}

Response (200):

{
  "success": true
}

Create and Link

POST /plugin-repos/create-and-link

Create a new external project and link a repository.

Request Body:

{
  "repo_full_name": "username/my-plugin",
  "name": "My Plugin",
  "description": "An awesome audio plugin",
  "visibility": "private"
}

Response (201):

{
  "project_id": "new-project-uuid",
  "name": "My Plugin",
  "source_repo_url": "https://github.com/username/my-plugin"
}

SDK API

Get SDK Status

GET /sdk/status

Check SDK availability.

Headers:

Authorization: Bearer YOUR_TOKEN

Response (200):

{
  "available": true,
  "version": "1.0.0",
  "documentation_url": "https://docs.beatconnect.com/sdk",
  "distribution_type": "public",
  "github_connected": true
}

Download SDK

GET /sdk/download

Get SDK download URL.

Headers:

Authorization: Bearer YOUR_TOKEN

Response (200):

{
  "url": "https://github.com/beatconnect/sdk/releases/...",
  "version": "1.0.0"
}

Error Responses

All errors follow this format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {}
}

Common Error Codes

Status	Code	Description
400	`bad_request`	Invalid request body
401	`unauthorized`	Missing or invalid token
403	`forbidden`	Insufficient permissions
404	`not_found`	Resource not found
429	`rate_limited`	Too many requests
500	`internal_error`	Server error

Rate Limits

Endpoint	Limit
Builds	10 requests/minute
Activation	60 requests/minute
General	100 requests/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642320000

Webhooks

Build Status Webhook

Configure in Project Settings to receive build status updates.

Payload:

{
  "event": "build.status",
  "build_id": "build-uuid",
  "status": "success",
  "project_id": "project-uuid",
  "version": "1.0.1",
  "timestamp": "2025-01-15T10:35:00Z"
}

Events:

build.queued
build.started
build.success
build.failed
build.cancelled

Signature Verification

Webhooks include a signature header:

X-BeatConnect-Signature: sha256=abc123...

Verify:

import hmac
import hashlib
 
def verify_signature(payload, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

SDK Libraries

JavaScript/TypeScript

import { BeatConnectSDK } from '@beatconnect/sdk';
 
const sdk = new BeatConnectSDK({
  token: 'YOUR_TOKEN'
});
 
// Trigger build
const build = await sdk.builds.create({
  projectId: 'project-uuid',
  platforms: ['macos', 'windows'],
  formats: ['vst3', 'au']
});
 
// Check status
const status = await sdk.builds.get(build.id);

Python

from beatconnect import BeatConnectSDK
 
sdk = BeatConnectSDK(token='YOUR_TOKEN')
 
# Trigger build
build = sdk.builds.create(
    project_id='project-uuid',
    platforms=['macos', 'windows'],
    formats=['vst3', 'au']
)
 
# Check status
status = sdk.builds.get(build['id'])

BeatConnect Docs

Explorer

API Reference

API Reference

Base URL

Authentication

Builds API

Trigger Build

Get Build Status

List Builds

Get Build Artifacts

Download Artifact

Cancel Build

Get Build Usage

Plugin Activation API

Activate

Deactivate

Validate

Get Status

Generate Key

List Project Keys

GitHub Integration API

Get Connection Status

Disconnect

Plugin Repositories API

Discover Repos

Link Repository

Unlink Repository

Create and Link

SDK API

Get SDK Status

Download SDK

Error Responses

Common Error Codes

Rate Limits

Webhooks

Build Status Webhook

Signature Verification

SDK Libraries

JavaScript/TypeScript

Python

Next Steps

Graph View

Table of Contents

Backlinks