Skip to content
docs

/ api reference

Projects

A project is one app: a repository or a directory, built and deployed by Hiraiship. Creating one also creates its production environment and its default domain, <slug>.hiraiship.app.

Build settings set the commands every deployment of the project uses, unless a deployment sets its own.

List projects

get/api/v1/projects

The workspace's projects, most recently created first, each with its default domain and its latest deployment (null for a project never deployed). search matches the name or the slug. limit is 20 by default, 50 at most; pass nextCursor back as cursor for the next page, until it is null.

Requires Viewer key or above (workspace.read)

Parameters

  • searchstringin query
  • cursorstringin query
  • limitintegerin query

Responses

  • 200A page of projects.
    Response fields
    • itemsobject[]required
      13 fields
      • idstringrequired
      • workspaceIdstringrequired
      • namestringrequired
      • slugstringrequired
      • productionEnvironmentIdstringrequired
      • installCommandstring | nullrequired
      • buildCommandstring | nullrequired
      • outputDirstring | nullrequired
      • rootDirectorystring | nullrequired
      • buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
      • createdAtstringrequired
      • defaultDomainstring | nullrequired
      • latestDeploymentobject | nullrequired
        25 fields
        • idstringrequired
        • environmentIdstringrequired
        • workerScriptRefstring | nullrequired
        • assetsManifestRefstring | nullrequired
        • status"queued" | "pending" | "success" | "failed"required
        • triggerSource"cli" | "upload"required
        • triggeredByUserIdstringrequired
        • gitShastring | nullrequired
        • gitRefstring | nullrequired
        • framework"rasengan" | "futon" | "hono" | "vite" | "static" | nullrequired
        • commitMessagestring | nullrequired
        • commitAuthorstring | nullrequired
        • repoUrlstring | nullrequired
        • deployedUrlstring | nullrequired
        • errorstring | nullrequired
        • createdAtstringrequired
        • finishedAtstring | nullrequired
        • dispatchStatus"not_applicable" | "pending" | "live" | "error"required
        • dispatchErrorstring | nullrequired
        • publishStartedAtstring | nullrequired
        • publishPlannedboolean
        • buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
        • startedAtstring | nullrequired
        • queuePositioninteger | null
        • queueReason"plan_limit" | "capacity" | nullrequired
    • nextCursorstring | nullrequired
  • 400The cursor is not one this route returned.
Request
curl "https://api.hiraiship.com/api/v1/projects" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Get a project by slug

get/api/v1/projects/by-slug/{slug}

The project and its production environment, found by slug instead of id.

Requires Viewer key or above (workspace.read)

Parameters

  • slugstringin pathrequired

Responses

  • 200The project and its production environment.
    Response fields
    • projectobjectrequired
      11 fields
      • idstringrequired
      • workspaceIdstringrequired
      • namestringrequired
      • slugstringrequired
      • productionEnvironmentIdstringrequired
      • installCommandstring | nullrequired
      • buildCommandstring | nullrequired
      • outputDirstring | nullrequired
      • rootDirectorystring | nullrequired
      • buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
      • createdAtstringrequired
    • environmentobjectrequired
      10 fields
      • idstringrequired
      • projectIdstringrequired
      • namestringrequired
      • workerNamestringrequired
      • activeDeploymentIdstring | nullrequired
      • suspendedReason"inactive" | "hibernated" | nullrequired
      • suspendedAtstring | nullrequired
      • neverHibernatebooleanrequired
      • variablesobject[]required
        2 shapes

        One of:

        secret: false
        • keystringrequired
        • secretfalserequired
        • valuestringrequired
        • notestring | nullrequired
        • updatedAtstringrequired
        secret: true
        • keystringrequired
        • secrettruerequired
        • notestring | nullrequired
        • updatedAtstringrequired
      • createdAtstringrequired
  • 404No project with that slug in this workspace.
Request
curl "https://api.hiraiship.com/api/v1/projects/by-slug/$SLUG" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Get a project

get/api/v1/projects/{projectId}

Requires Viewer key or above (workspace.read)

Parameters

  • projectIdstringin pathrequired

Responses

  • 200The project.
    Response fields
    • idstringrequired
    • workspaceIdstringrequired
    • namestringrequired
    • slugstringrequired
    • productionEnvironmentIdstringrequired
    • installCommandstring | nullrequired
    • buildCommandstring | nullrequired
    • outputDirstring | nullrequired
    • rootDirectorystring | nullrequired
    • buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
    • createdAtstringrequired
  • 404No such project in this workspace.
Request
curl "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Create a project

post/api/v1/projects

Creates the project with its production environment and its default domain, <slug>.hiraiship.app. Nothing is deployed yet: start a deployment on the returned environment. The slug is unique across Hiraiship and can never change.

Requires Developer key or above (project.create)

Body

  • namestringrequired
  • slugstringrequired
  • rootDirectorystring | null

    at most 1000 characters

Responses

  • 201The project, its production environment and its default domain.
    Response fields
    • projectobjectrequired
      11 fields
      • idstringrequired
      • workspaceIdstringrequired
      • namestringrequired
      • slugstringrequired
      • productionEnvironmentIdstringrequired
      • installCommandstring | nullrequired
      • buildCommandstring | nullrequired
      • outputDirstring | nullrequired
      • rootDirectorystring | nullrequired
      • buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
      • createdAtstringrequired
    • environmentobjectrequired
      10 fields
      • idstringrequired
      • projectIdstringrequired
      • namestringrequired
      • workerNamestringrequired
      • activeDeploymentIdstring | nullrequired
      • suspendedReason"inactive" | "hibernated" | nullrequired
      • suspendedAtstring | nullrequired
      • neverHibernatebooleanrequired
      • variablesobject[]required
        2 shapes

        One of:

        secret: false
        • keystringrequired
        • secretfalserequired
        • valuestringrequired
        • notestring | nullrequired
        • updatedAtstringrequired
        secret: true
        • keystringrequired
        • secrettruerequired
        • notestring | nullrequired
        • updatedAtstringrequired
      • createdAtstringrequired
    • domainobjectrequired
      11 fields
      • idstringrequired
      • environmentIdstringrequired
      • hostnamestringrequired
      • isDefaultbooleanrequired
      • status"pending" | "active" | "error"required
      • cloudflareHostnameIdstring | nullrequired
      • cloudflareVerificationobject | nullrequired
        2 fields
        • recordsobject[]required
          4 fields
          • type"CNAME" | "ALIAS" | "TXT"required
          • namestringrequired
          • valuestringrequired
          • purpose"routing" | "ownership" | "certificate"required
        • errorsstring[]required
      • lastCheckedAtstring | nullrequired
      • redirectToDomainIdstring | nullrequired
      • redirectStatusCode301 | 302 | 307 | 308 | object | nullrequired
      • createdAtstringrequired
  • 400The name is empty; the slug has characters other than lowercase letters, digits and hyphens, is longer than 63 characters, starts or ends with a hyphen, or is reserved (www, api, app, admin, …); or rootDirectory could leave the repository.
  • 409That slug is taken: by a project, or by one deleted less than 30 days ago in another workspace.
  • 429Too many projects created in the last hour for your plan. Retry after the Retry-After header's seconds.

    Body: see Errors

Request
curl -X POST "https://api.hiraiship.com/api/v1/projects" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme site",
    "slug": "acme-site"
  }'

Rename a project

patch/api/v1/projects/{projectId}

Changes the project's display name. The slug, and with it the default hostname, never changes.

Requires Developer key or above (project.update)

Parameters

  • projectIdstringin pathrequired

Body

  • namestringrequired

    at most 64 characters

Responses

  • 200The renamed project.
    Response fields
    • idstringrequired
    • workspaceIdstringrequired
    • namestringrequired
    • slugstringrequired
    • productionEnvironmentIdstringrequired
    • installCommandstring | nullrequired
    • buildCommandstring | nullrequired
    • outputDirstring | nullrequired
    • rootDirectorystring | nullrequired
    • buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
    • createdAtstringrequired
  • 400An empty name, one over 64 characters, or a body with any other field (the slug can't be changed).
  • 404No such project in this workspace.
Request
curl -X PATCH "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme marketing site"
  }'

Delete a project

delete/api/v1/projects/{projectId}

Takes every environment of the project offline and deletes its domains, environment variables and queued builds. confirm must be the project's slug. This can't be undone; the slug can be used by a new project afterwards. Usage already recorded this month stays on the workspace's bill.

Requires Admin key or above (project.delete)

Parameters

  • projectIdstringin pathrequired
  • confirmstringin queryrequired

Responses

  • 204Deleted.
  • 400confirm isn't the project's slug (code: confirmation_mismatch).
  • 404No such project in this workspace.
Request
curl -X DELETE "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Update build settings

patch/api/v1/projects/{projectId}/build-settings

The install command, build command, output directory and build machine every future deployment of the project uses, unless the deployment sets its own. An omitted field is left unchanged; null goes back to the framework's default (the plan's default machine for buildMachine). rootDirectory is the app's directory in its GitHub repository, for a monorepo (apps/web; null or . for the root): the framework, the build command and the output directory are relative to it, and dependencies are installed where the nearest lockfile is. A deployment from the CLI builds the directory it was run in instead. Deployments already made are not rebuilt.

Requires Developer key or above (project.update)

Parameters

  • projectIdstringin pathrequired

Body

  • installCommandstring | null

    at most 500 characters

  • buildCommandstring | null

    at most 500 characters

  • outputDirstring | null

    at most 500 characters

  • rootDirectorystring | null

    at most 1000 characters

  • buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | null

Responses

  • 200The updated project.
    Response fields
    • idstringrequired
    • workspaceIdstringrequired
    • namestringrequired
    • slugstringrequired
    • productionEnvironmentIdstringrequired
    • installCommandstring | nullrequired
    • buildCommandstring | nullrequired
    • outputDirstring | nullrequired
    • rootDirectorystring | nullrequired
    • buildMachine"standard-1" | "standard-2" | "standard-3" | "standard-4" | nullrequired
    • createdAtstringrequired
  • 400rootDirectory is absolute, contains .. or a backslash, or is over 255 characters.
  • 402Your plan does not allow that build machine (quota: build_machine), or a spend limit of $0 allows only the default one.

    Body: see Errors

  • 404No such project in this workspace.
Request
curl -X PATCH "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID/build-settings" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "buildCommand": "pnpm build",
    "outputDir": "dist",
    "rootDirectory": "apps/web",
    "buildMachine": "standard-2"
  }'