SISuperintelligenceDocs

Search docs

Search every page of the documentation.

API reference

Projects

Create, read, update, transfer and delete projects.

A project links a repository to builds and deployments.

GET /v1/orgs/:orgId/projects

Lists the organization's projects.

Auth: user access token or platform agent key · Scope: projects:read · Allowed: deployments:read; domains:read

Path parameterDescription
:orgIdOrganization id (org_…).
Query parameterTypeRequiredNotes
include"summary"No

Response 200

{
  projects: {
    name: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    projectId: string
    repoId?: string
    productionBranch?: string
    framework?: "static" | "nextjs" | "node"
    rootDirectory?: string
    buildCommand?: string
    installCommand?: string
    outputDirectory?: string
    location: string
    productionDeploymentId?: string
  }[]
}
| {
  projects: {
    latest?: {
      error?: string
      status?: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
      createdAt?: number
      updatedAt?: number
      region?: string
      orgId: string
      createdBy?: string
      projectId: string
      location: string
      deploymentId: string
      target: "preview" | "production"
      branch?: string
      commitSha?: string
      commitMessage?: string
      commitAuthor?: string
      host?: string
      buildId?: string
      buildDurationMs?: number
      readyAt?: number
      crons?: string
      envHash?: string
      previousDeploymentId?: string
      reason?: string
      buildMetrics?: {
        restoreMs?: number
        installMs?: number
        buildMs?: number
        uploadMs?: number
        saveMs?: number
        depsCache?: "hit" | "partial" | "miss" | "off"
        nextCache?: "hit" | "partial" | "miss" | "off"
        packageManager?: string
        installDir?: string
      }
    }
    production?: {
      error?: string
      status?: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
      createdAt?: number
      updatedAt?: number
      region?: string
      orgId: string
      createdBy?: string
      projectId: string
      location: string
      deploymentId: string
      target: "preview" | "production"
      branch?: string
      commitSha?: string
      commitMessage?: string
      commitAuthor?: string
      host?: string
      buildId?: string
      buildDurationMs?: number
      readyAt?: number
      crons?: string
      envHash?: string
      previousDeploymentId?: string
      reason?: string
      buildMetrics?: {
        restoreMs?: number
        installMs?: number
        buildMs?: number
        uploadMs?: number
        saveMs?: number
        depsCache?: "hit" | "partial" | "miss" | "off"
        nextCache?: "hit" | "partial" | "miss" | "off"
        packageManager?: string
        installDir?: string
      }
    }
    productionHost?: string
    repo?: {
      resourceId: string
      name: string
    }
    domains?: {
      hostname: string
      status?: "error" | "active" | "pending" | "verifying"
      redirectTo?: string
    }[]
    name: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    projectId: string
    repoId?: string
    productionBranch?: string
    framework?: "static" | "nextjs" | "node"
    rootDirectory?: string
    buildCommand?: string
    installCommand?: string
    outputDirectory?: string
    location: string
    productionDeploymentId?: string
  }[]
}

Errors

StatusMessage
404Organization not found
404Not found
404Commit not found

POST /v1/orgs/:orgId/projects

Creates a project. Without location, the registry's default location is used.

Auth: user access token or platform agent key · Scope: projects:write

Path parameterDescription
:orgIdOrganization id (org_…).

Request body

FieldTypeRequiredDefaultNotes
namestringYes1–64 characters; trimmed
slugstringYesmatches ^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$
repoIdstringNo
framework"nextjs" | "static" | "node"No"nextjs"
rootDirectorystringNo"."up to 256 characters; trimmed
locationstringNo

Response 201

{
  project: {
    name: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    projectId: string
    repoId?: string
    productionBranch?: string
    framework?: "static" | "nextjs" | "node"
    rootDirectory?: string
    buildCommand?: string
    installCommand?: string
    outputDirectory?: string
    location: string
    productionDeploymentId?: string
  }
  deployment: null | {
    deploymentId: string
    host: string
    target: "preview" | "production"
  }
}

Errors

StatusMessage
400Repository not found in this organization.
400Unknown location: …
409A project with this slug exists.

GET /v1/orgs/:orgId/projects/:projectId

A project with its most recent deployments and, once it has a production deployment, its production hostname.

Auth: user access token or platform agent key · Scope: projects:read · Allowed: domains:read

Path parameterDescription
:orgIdOrganization id (org_…).
:projectIdProject id (prj_…).

Response 200

{
  project: {
    name: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    projectId: string
    repoId?: string
    productionBranch?: string
    framework?: "static" | "nextjs" | "node"
    rootDirectory?: string
    buildCommand?: string
    installCommand?: string
    outputDirectory?: string
    location: string
    productionDeploymentId?: string
  }
  productionHost?: string
  deployments: {
    error?: string
    status?: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
    createdAt?: number
    updatedAt?: number
    region?: string
    orgId: string
    createdBy?: string
    projectId: string
    location: string
    deploymentId: string
    target: "preview" | "production"
    branch?: string
    commitSha?: string
    commitMessage?: string
    commitAuthor?: string
    host?: string
    buildId?: string
    buildDurationMs?: number
    readyAt?: number
    crons?: string
    envHash?: string
    previousDeploymentId?: string
    reason?: string
    buildMetrics?: {
      restoreMs?: number
      installMs?: number
      buildMs?: number
      uploadMs?: number
      saveMs?: number
      depsCache?: "hit" | "partial" | "miss" | "off"
      nextCache?: "hit" | "partial" | "miss" | "off"
      packageManager?: string
      installDir?: string
    }
  }[]
  production?: {
    error?: string
    status?: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
    createdAt?: number
    updatedAt?: number
    region?: string
    orgId: string
    createdBy?: string
    projectId: string
    location: string
    deploymentId: string
    target: "preview" | "production"
    branch?: string
    commitSha?: string
    commitMessage?: string
    commitAuthor?: string
    host?: string
    buildId?: string
    buildDurationMs?: number
    readyAt?: number
    crons?: string
    envHash?: string
    previousDeploymentId?: string
    reason?: string
    buildMetrics?: {
      restoreMs?: number
      installMs?: number
      buildMs?: number
      uploadMs?: number
      saveMs?: number
      depsCache?: "hit" | "partial" | "miss" | "off"
      nextCache?: "hit" | "partial" | "miss" | "off"
      packageManager?: string
      installDir?: string
    }
  }
  repo?: {
    resourceId: string
    name: string
  }
  domains?: {
    message?: string
    status?: "error" | "active" | "pending" | "verifying"
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    hostname: string
    tenantId?: string
    certificateArn?: string
    records?: string
    zone?: string
    dnsProvider?: string
    checkedAt?: number
    redirectTo?: string
  }[]
  functionConfig: {
    memoryMb: 1024
    timeoutSeconds: 30
    architecture: "arm64"
    runtime: "nodejs22.x"
  }
}

Errors

StatusMessage
404Project not found
404Organization not found
404Not found
404Commit not found

PATCH /v1/orgs/:orgId/projects/:projectId

Updates the name, repository link, production branch, root directory or build and install commands. repoId: null unlinks the repository.

Auth: user access token or platform agent key · Scope: projects:write

Path parameterDescription
:orgIdOrganization id (org_…).
:projectIdProject id (prj_…).

Request body

FieldTypeRequiredNotes
namestringNo1–64 characters; trimmed
slugstringNomatches ^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$
framework"nextjs" | "static" | "node"No
repoIdstringNocan be null
productionBranchstringNo1–255 characters; trimmed
rootDirectorystringNoup to 256 characters; trimmed
buildCommandany JSONYes
installCommandany JSONYes
outputDirectoryany JSONYes
locationstringNoat least 1 character

Response 200

{
  project: {
    name: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    projectId: string
    repoId?: string
    productionBranch?: string
    framework?: "static" | "nextjs" | "node"
    rootDirectory?: string
    buildCommand?: string
    installCommand?: string
    outputDirectory?: string
    location: string
    productionDeploymentId?: string
  }
}
| {
  project: {
    name: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    projectId: string
    repoId?: string
    productionBranch?: string
    framework?: "static" | "nextjs" | "node"
    rootDirectory?: string
    buildCommand?: string
    installCommand?: string
    outputDirectory?: string
    location: string
    productionDeploymentId?: string
  }
  deployment: null | {
    deploymentId: string
    host: string
    target: "preview" | "production"
  }
}

Errors

StatusMessage
400Repository not found in this organization.
400Unknown location: …
404Project not found
404Organization not found
409A project with this slug exists.

POST /v1/orgs/:orgId/projects/:projectId/transfer

Moves a project to another org the caller administers. Deployments, domains, environment variables (re-encrypted for the new org) and crons move with it; the repository stays and is disconnected, and linked storage must be unlinked first.

Auth: user access token or platform agent key · Scope: org:write

Path parameterDescription
:orgIdOrganization id (org_…).
:projectIdProject id (prj_…).

Request body

FieldTypeRequiredNotes
orgIdstringYesat least 1 character

Response 200

{
  project: {
    name: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    projectId: string
    productionBranch?: string
    framework?: "static" | "nextjs" | "node"
    rootDirectory?: string
    buildCommand?: string
    installCommand?: string
    outputDirectory?: string
    location: string
    productionDeploymentId?: string
  }
  org: {
    orgId: string
    slug: string
  }
}

Errors

StatusMessage
400The project is already in this organization.
404Project not found
404Organization not found
409Unlink this project's databases and buckets first. They stay in this organization.
409Wait for the deployment in progress to finish.
409… already has a project with this slug. Rename it first.

DELETE /v1/orgs/:orgId/projects/:projectId

Deletes a project: its domains (routes and certificates), crons, server functions, routes, deployment records and environment variables. Linked storage is unlinked, not deleted, and the repository is kept.

Auth: user access token or platform agent key · Scope: projects:write

Path parameterDescription
:orgIdOrganization id (org_…).
:projectIdProject id (prj_…).

Response 204 with no body.

Errors

StatusMessage
404Project not found
404Organization not found
409Wait for the deployment in progress to finish.
502Couldn't remove all of the project's resources. Try again.