POST /api/v1/projects/import — Import a GitHub Repository

The Import Project endpoint is the starting point for every new application on the platform. It creates a project record linked to a GitHub repository, optionally stores encrypted environment variables, registers a GitHub webhook so future pushes automatically trigger deployments, and then queues an initial deployment against the specified default branch — all in a single atomic request. POST /api/v1/projects/import

Authentication

This endpoint requires an active session and a connected GitHub account. Your GitHub OAuth access token is retrieved from the database and used to register the webhook on your behalf. See Authentication for details on obtaining a session token.

Request

Body Parameters

repositoryFullName

string

required

Full GitHub repository identifier in owner/repo format, e.g. "acme/my-nextjs-app". This must be a repository the authenticated GitHub account has access to.

defaultBranch

string

required

The branch to use for production deployments and the initial build, e.g. "main" or "production".

name

string

required

Human-readable display name for the project as it will appear in the dashboard.

buildCommand

string

Custom build command to override auto-detection, e.g. "npm run build". If omitted or null, the platform will detect the framework and choose an appropriate build command automatically.

startCommand

string

Custom start command to override auto-detection, e.g. "node dist/server.js". If omitted or null, auto-detection is used.

rootDirectory

string

Path to the application root within the repository, e.g. "apps/web". Defaults to the repository root if omitted.

envs

array

List of environment variables to store with the project. Defaults to an empty array if omitted.

[
  { "key": "DATABASE_URL", "value": "postgres://..." },
  { "key": "API_SECRET",   "value": "s3cr3t" }
]

Each item must have:

key (string) — environment variable name.
value (string) — plaintext environment variable value (encrypted before storage — see note below).

Webhook registration: Upon successful project creation, the platform automatically registers a push event webhook in the GitHub repository using your OAuth access token. This webhook enables automatic deployments whenever commits are pushed to any tracked branch.

Environment variable encryption: All value fields in the envs array are encrypted using the platform’s master encryption key before being written to the database. Values returned from subsequent API calls will be in their encrypted form. Never store plaintext secrets outside of this endpoint’s request body.

Response

A successful 200 OK response returns both the newly created project and the initial deployment record:

{
  "project": Project,
  "deployment": Deployment
}

Response Fields

project

object

The newly created project record.

Show Project

string

Unique project identifier (cuid).

userId

string

ID of the owning user.

name

string

Display name supplied in the request.

repositoryFullName

string

Full GitHub repository path as supplied.

defaultBranch

string

Default branch as supplied.

buildCommand

string | null

Custom build command, or null.

startCommand

string | null

Custom start command, or null.

rootDirectory

string | null

Application root path, or null.

deploymentUrl

string | null

null immediately after creation; populated once the first deployment succeeds.

customDomain

string | null

Always null at creation time.

customDomainVerified

boolean

Always false at creation time.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

deployment

object

The initial deployment record that was queued immediately after project creation.

Show Deployment

string

Unique deployment identifier (cuid).

projectId

string

ID of the parent project.

branch

string

The defaultBranch value from the request.

commitHash

string | null

null initially; set once the repository is cloned.

status

DeploymentStatus

Initial status is PENDING.

url

string | null

null until the deployment succeeds.

port

integer | null

null until a container port is allocated.

logs

string | null

null initially; populated as the build progresses.

error

string | null

null initially; populated if the deployment fails.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

completedAt

string | null

null while in-progress; set when a terminal state is reached.

Example

curl -X POST https://your-domain.com/api/v1/projects/import \
  -H 'Content-Type: application/json' \
  -b 'better-auth.session_token=YOUR_SESSION_TOKEN' \
  -d '{
    "repositoryFullName": "acme/my-nextjs-app",
    "defaultBranch": "main",
    "name": "My Next.js App",
    "buildCommand": null,
    "startCommand": null,
    "rootDirectory": null,
    "envs": [
      { "key": "DATABASE_URL", "value": "postgres://user:pass@host/db" },
      { "key": "NEXT_PUBLIC_API_URL", "value": "https://api.example.com" }
    ]
  }'

Example response:

{
  "project": {
    "id": "clx4z2k0e0000abc123def456",
    "userId": "user_01hxyz",
    "name": "My Next.js App",
    "repositoryFullName": "acme/my-nextjs-app",
    "defaultBranch": "main",
    "buildCommand": null,
    "startCommand": null,
    "rootDirectory": null,
    "deploymentUrl": null,
    "customDomain": null,
    "customDomainVerified": false,
    "createdAt": "2024-06-01T12:00:00.000Z",
    "updatedAt": "2024-06-01T12:00:00.000Z"
  },
  "deployment": {
    "id": "clx5a3b1c0001xyz789ghi012",
    "projectId": "clx4z2k0e0000abc123def456",
    "branch": "main",
    "commitHash": null,
    "status": "PENDING",
    "url": null,
    "port": null,
    "logs": null,
    "error": null,
    "createdAt": "2024-06-01T12:00:01.000Z",
    "updatedAt": "2024-06-01T12:00:01.000Z",
    "completedAt": null
  }
}

Error Responses

Status	Error Message	Description
`400`	`"Missing required fields"`	One or more of `repositoryFullName`, `defaultBranch`, or `name` were absent.
`401`	`"Unauthorized"`	No valid session cookie was provided.
`401`	`"No GitHub access token found"`	The authenticated user has not connected a GitHub account.
`500`	`"Internal server error"`	An unexpected server-side error occurred (e.g. webhook registration failure).

Overview

Projects

Deployments

Webhooks

POST /api/v1/projects/import — Import a GitHub Repository

Authentication

Request

Body Parameters

Response

Response Fields

Example

Error Responses

Build docs developers (and LLMs) love

Overview

Projects

Deployments

Webhooks

Documentation Index

​Authentication

​Request

​Body Parameters

​Response

​Response Fields

​Example

​Error Responses

Build docs developers (and LLMs) love

Authentication

Request

Body Parameters

Response

Response Fields

Example

Error Responses