API docs by Redocly

Builtiful API (1.0.0)

Download OpenAPI specification:

E-mail: dndx@idndx.com

Builtiful API spec

Frontend

Frontend APIs

System healthcheck endpoint

Returns system status with a updating UUID v7 identifier and database timestamp

Responses

Response samples

Content type
application/json
{
  • "message": "it works!",
  • "db_time": {
    }
}

GitHub OAuth login redirect

Redirects the user to GitHub's OAuth authorization page

query Parameters
redirect_uri
string
Example: redirect_uri=https://app-dev.builtiful.io

The full URI to redirect user back to once the OAuth flow completes. This is usually the frontend URI.

Responses

Response samples

Content type
application/json
{
  • "message": "Something went wrong during request processing, this issue has been logged and reported to our team"
}

Logout endpoint

Logs out the user by clearing their session and optionally redirects to a specified URI

query Parameters
redirect_uri
string <uri>
Example: redirect_uri=https://app-dev.builtiful.io

Full URI to redirect to after successful logout

Responses

Response samples

Content type
application/json
{
  • "message": "Successfully logged out"
}

Get current logged in user

Returns information about the currently authenticated user

Responses

Response samples

Content type
application/json
{
  • "user": {
    }
}

List tenants accessible to the current user

Returns a list of all tenants and their GitHub installation details accessible by the logged in user.

Responses

Response samples

Content type
application/json
{
  • "tenants": [
    ],
  • "total_count": 1
}

List jobs for a tenant

Returns a paginated list of jobs associated with the specified tenant, with most recent ones first.

To implement pagination, one will use the limit and one of starting_after or ending_before.

For "Next Page", the starting_after parameter will be used with the UUID of the last item of the current page.

For "Prev Page", the ending_before parameter will be used with the UUID of the first item of the current page.

To detect if more item is available, one can fetch 1 item more than the display page size from the API. For example, if the page size is 10, set limit = 11 (but only display first 10) and if the API returned 11 items, that means more items are available and the UUID of the 10th item will be used as the cursor value for fetching the next page.

path Parameters
tenant_id
required
string <uuid>
Example: 01234567-89ab-7cde-ef01-234567890abc

UUID of the tenant

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

This specifies a limit on the number of objects to return.

starting_after
string <uuid>
Example: starting_after=01234567-89ab-7cde-ef01-234567890abc

A cursor to use in pagination. starting_after is an object UUID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending with 01234567-89ab-7cde-ef01-234567890abc, your subsequent call can include starting_after=01234567-89ab-7cde-ef01-234567890abc to fetch the next page of the list. This option is mutually exclusive with ending_before.

ending_before
string <uuid>
Example: ending_before=01234567-89ab-7cde-ef01-234567890abc

A cursor to use in pagination. ending_before is an object UUID that defines your place in the list. For example, if you make a list request and receive 100 objects, starting with 01234567-89ab-7cde-ef01-234567890abc, your subsequent call can include ending_before=01234567-89ab-7cde-ef01-234567890abc to fetch the previous page of the list. This option is mutually exclusive with starting_after.

Responses

Response samples

Content type
application/json
{
  • "jobs": [
    ],
  • "total_count": 1
}

Get tenant email

Returns the current email address associated with the specified tenant

path Parameters
tenant_id
required
string <uuid>
Example: 01234567-89ab-7cde-ef01-234567890abc

UUID of the tenant

Responses

Response samples

Content type
application/json
{
  • "email": "org@example.com"
}

Update tenant email

Initiates the email update process for a tenant. Sends a verification email to the new address with a link to confirm the change.

path Parameters
tenant_id
required
string <uuid>
Example: 01234567-89ab-7cde-ef01-234567890abc

UUID of the tenant

Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "new-email@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Something went wrong during request processing, this issue has been logged and reported to our team"
}

Verify tenant email update

Confirms the email update for a tenant using a JWT token provided in the verification email

path Parameters
tenant_id
required
string <uuid>
Example: 01234567-89ab-7cde-ef01-234567890abc

UUID of the tenant

query Parameters
jwt
required
string

JWT token received in the verification email

Responses

Response samples

Content type
application/json
{
  • "message": "Something went wrong during request processing, this issue has been logged and reported to our team"
}

GitHub callbacks

GitHub callback APIs

GitHub OAuth callback handler

Handles the OAuth callback from GitHub, sets session cookie for authenticated user

query Parameters
code
required
string

OAuth authorization code from GitHub

state
string

State parameter for CSRF protection. This will be checked against the state stored inside the signed cookie.

Responses

Response samples

Content type
application/json
{
  • "message": "Something went wrong during request processing, this issue has been logged and reported to our team"
}

GitHub App setup handler

Handles the OAuth setup callback from GitHub. This usually occurs when user manuallly installs the App via GitHub marketplace.

Technically this will get passed the installation ID and we could redirect the user into the newly installed org directly, but this haven't been implemented.

Responses

GitHub webhook receiver

Responses

Provisioner

Provisioner APIs

System healthcheck endpoint

Returns system status with a updating UUID v7 identifier and database timestamp

Responses

Response samples

Content type
application/json
{
  • "message": "it works!",
  • "db_time": {
    }
}

Dequeue a job that is waiting to be started

Returns zero or one job that can be run on the provisioner based on available resources

query Parameters
available_vcpus
required
integer >= 1
Example: available_vcpus=16

Number of vCPUs currently available on the provisioner. API will not return jobs that require more CPUs to run than available_vcpus

cpu_architecture
required
string
Enum: "Amd64" "Arm64"

CPU architecture of the host, API will only return jobs that are same architecture as cpu_architecture

host
required
string
Example: host=amd64-01.hel.hetzner.farm.builtiful.net

Hostname of the provisioner

Responses

Response samples

Content type
application/json
{
  • "new_job": {
    }
}