Return to Docs

Builder API (v1)

Download OpenAPI specification:Download

Authenticates a user and creates a session

Authenticates a user and creates a session

path Parameters
code
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "73089155726360582",
  • "name": "reset",
  • "email": "reset@chef.io",
  • "token": "0b79bab50daca910b000d4f1a2b675d604257e42",
  • "flags": 0,
  • "oauth_token": "bb79bab50dbcab10b000d4f1a2bb75d604257e42"
}

Get list of unique packages for specified origin

Get list of unique packages for specified origin

path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1234567890,
  • "origin": "xyz",
  • "name": "abc",
  • "visibility": "private",
  • "owner_id": 77730215748435970
}

Retrieves the list of reverse dependencies for thi

Retrieves the list of reverse dependencies for this package (on-prem setup not supported).

path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
{
  • "origin": "core",
  • "name": "linux-headers",
  • "rdeps": [
    ]
}

Retrieves the list of reverse dependencies for thi

Retrieves the list of reverse dependencies for this package, collated into build groups that can be build in parallel (on-prem setup not supported)

path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
{
  • "origin": "core",
  • "name": "linux-headers",
  • "rdeps": [
    ]
}

Returns the health of the service

Returns the health of the service

Responses

Returns the health of the service

Returns the health of the service

Responses

Get content from github

Get content from github

path Parameters
install_id
required
string
repo_id
required
string
path
required
string

Responses

Response samples

Content type
application/json
{ }

Validates registry credentials

Validates registry credentials

path Parameters
registry_type
required
string
Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
{
  • "user": "user",
  • "password": "password",
  • "url": "url"
}

Retrieve your profile

Retrieve your profile

Authorizations:
oauth_2_0

Responses

Response samples

Content type
application/json
{
  • "id": "1234567890",
  • "name": "jimmy",
  • "email": "jimmy@example.com"
}

Update your profile

Update your profile

Authorizations:
oauth_2_0
Request Body schema: application/json
object

Responses

Request samples

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

Retrieve your personal access tokens

Retrieve your personal access tokens

Authorizations:
oauth_2_0

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Generate a new personal access token

Generate a new personal access token

Authorizations:
oauth_2_0
Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
null

Delete (revoke) a personal access token

Delete (revoke) a personal access token

Authorizations:
oauth_2_0
path Parameters
id
required
string
Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
null

Get the status of the given job

Get the status of the given job

path Parameters
jobId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "73089155726360582",
  • "origin": "core",
  • "project": "nginx",
  • "version": "1.0.0",
  • "release": "20170505001756",
  • "state": "Complete",
  • "created_at": "2017-05-05 00:42:35.213765+00",
  • "build_started_at": "2017-05-05 00:43:11.729835+00",
  • "build_finished_at": "2017-05-05 00:44:00.896919+00"
}

Get the build log (or a portion thereof) for the g

Get the build log (or a portion thereof) for the given job. Until an SSE endpoint can be implemented, this endpoint can be used to poll for the logs of a currently-running job; use of the start query parameter ensures that only the portion of the log that is "new", relative to a prior request, will be retrieved.

path Parameters
jobId
required
string
query Parameters
start
integer >= 0
Default: 0
Example: start=100

Return the portion of the log output that starts at the zero-indexed line specified. A request with no given value defaults to 0; in other words, the entire log will be sent back.

color
boolean
Default: false

Whether or not to include embedded ANSI color codes in the log output. By default, all ANSI sequences are removed, yielding plain output.

The following values are interpreted as true:

  • true
  • TRUE
  • t
  • T
  • 1
  • on
  • ON

The following values are interpreted as false:

  • false
  • FALSE
  • f
  • F
  • 0
  • off
  • OFF

All other values are considered false.

Responses

Response samples

Content type
application/json
{
  • "start": 0,
  • "stop": 2,
  • "content": [
    ],
  • "is_complete": false
}

Cancels a job group

Cancels a job group

path Parameters
id
required
string

Responses

Rebuilds a job group

Rebuilds a job group

path Parameters
id
required
string

Responses

Promote every successful project in a job group to

Promote every successful project in a job group to the specified channel

path Parameters
id
required
string
channel
required
string

Responses

Demote every successful project in a job group to

Demote every successful project in a job group to the specified channel

path Parameters
id
required
string
channel
required
string

Responses

Get invitations for the specified user

Get invitations for the specified user

Authorizations:
oauth_2_0

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "origin": "core",
  • "account_id": 1,
  • "account_name": "hab",
  • "owner_id": 1331,
  • "ignored": false
}

Get origins for the specified user

Get origins for the specified user

Authorizations:
oauth_2_0

Responses

Response samples

Content type
application/json
[
  • "origin1",
  • "origin2"
]

Creates a new project for building a Habitat plan

Creates a new project for building a Habitat plan scoped to the given origin. The resulting project will be created with an identifier containing the origin and name of the project the plan is building separated by a forward slash (i.e. core/nginx).

Authorizations:
oauth_2_0
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "origin": "core",
  • "plan_path": "components/builder-api/plan.sh",
  • "installation_id": 1234,
  • "repo_id": 4567
}

Response samples

Content type
application/json
{}

Get the list of project names for the specified or

Get the list of project names for the specified origin

path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
[
  • "foo",
  • "bar",
  • "baz"
]

Return the project matching the given ID

Return the project matching the given ID

path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
{}

Update the project matching the given ID

Update the project matching the given ID

Authorizations:
oauth_2_0
path Parameters
origin
required
string
name
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "plan_path": "components/builder-api/plan.sh",
  • "github": {
    }
}

Destroys the project matching the given ID

Destroys the project matching the given ID

Authorizations:
oauth_2_0
path Parameters
origin
required
string
name
required
string

Responses

Toggle the visibility settings on a project. Publi

Toggle the visibility settings on a project. Public projects that are made private will change to hidden instead. Changes made to a project's visibility settings will cascade to its packages.

path Parameters
origin
required
string
name
required
string
visibility
required
string

Responses

Retrieve the most recently started jobs for the gi

Retrieve the most recently started jobs for the given project.

path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
{
  • "range_start": 0,
  • "range_end": 5,
  • "total_count": 6,
  • "data": [
    ]
}

Get the specified integration

Get the specified integration

path Parameters
origin
required
string
name
required
string
integration
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "project_id": 121,
  • "integration_id": 14641,
  • "origin": "core",
  • "body": "NoContent",
  • "created_at": "2017-05-05 00:43:11.729835+00"
}

Creates a project integration

Creates a project integration

path Parameters
origin
required
string
name
required
string
integration
required
string

Responses

Deletes an integration

Deletes an integration

path Parameters
origin
required
string
name
required
string
integration
required
string

Responses

Create a new origin

Create a new origin

Authorizations:
oauth_2_0
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "reset",
  • "owner_id": 1965
}

Response samples

Content type
application/json
{
  • "id": 1965,
  • "name": "core",
  • "owner_id": 3861225,
  • "default_package_visibility": "Public"
}

Get origin

Get origin

path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1965,
  • "name": "test",
  • "owner_id": 1965,
  • "default_package_visibility": "Public"
}

Update existing origin

Update existing origin

path Parameters
origin
required
string

Responses

Delete an origin

Delete an origin

path Parameters
origin
required
string

Responses

List all members of an origin

List all members of an origin

path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
{
  • "origin": "core",
  • "members": [
    ]
}

Delete origin member

Delete origin member

Authorizations:
oauth_2_0
path Parameters
origin
required
string
user
required
string

Responses

Update an origin member's role

Update an origin member's role

Authorizations:
oauth_2_0
path Parameters
origin
required
string
user
required
string
query Parameters
role
required
string

Responses

Retrieve an origin member's role

Retrieve an origin member's role

Authorizations:
oauth_2_0
path Parameters
origin
required
string
user
required
string

Responses

Response samples

Content type
application/json
{
  • "role": "administrator"
}

Create an invitation to this origin for this user

Create an invitation to this origin for this user

Authorizations:
oauth_2_0
path Parameters
origin
required
string
user
required
string

Responses

Transfer ownership of origin to new origin member

Transfer ownership of origin to new origin member

Authorizations:
oauth_2_0
path Parameters
origin
required
string
user
required
string

Responses

Leave an origin you no longer wish to be a member

Leave an origin you no longer wish to be a member of

Authorizations:
oauth_2_0
path Parameters
origin
required
string

Responses

Return list of invitations for the specified origi

Return list of invitations for the specified origin

Authorizations:
oauth_2_0
path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
{
  • "origin": "test",
  • "invitations": [
    ]
}

Return a list of key revisions for an organization

Return a list of key revisions for an organization

Authorizations:
oauth_2_0
path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a new set of keys

Create a new set of keys

path Parameters
origin
required
string

Responses

Download latest origin key

Download latest origin key

Authorizations:
oauth_2_0
path Parameters
origin
required
string

Responses

Download a key revision for a specific origin

Download a key revision for a specific origin

Authorizations:
oauth_2_0
path Parameters
origin
required
string
revision
required
string

Responses

Upload a new key revision for an origin

Upload a new key revision for an origin

Authorizations:
oauth_2_0
path Parameters
origin
required
string
revision
required
string
Request Body schema: text/plain
any

Responses

Download public encryption key for origin response

Download public encryption key for origin responses

path Parameters
origin
required
string

Responses

Upload a secret payload body

Upload a secret payload body

path Parameters
origin
required
string

Responses

Get a list of all secrets for the specified origin

Get a list of all secrets for the specified origin

path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

Delete a secret for an origin given a secret name

Delete a secret for an origin given a secret name

path Parameters
origin
required
string
secret
required
string

Responses

Retrieve the latest secret key

Retrieve the latest secret key

path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "11",
  • "origin_id": "121",
  • "name": "core",
  • "revision": "20210407112205",
  • "body": "OK",
  • "owner_id": "1331"
}

Upload origin secret key

Upload origin secret key

Authorizations:
oauth_2_0
path Parameters
origin
required
string
revision
required
string

Responses

Get an object of all integrations

Get an object of all integrations

Authorizations:
oauth_2_0
path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
{
  • "names": [
    ]
}

Get integrations for specified origin

Get integrations for specified origin

path Parameters
origin
required
string
integration
required
string

Responses

Response samples

Content type
application/json
{
  • "names": [
    ]
}

Get integration for specified origin and name

Get integration for specified origin and name

path Parameters
origin
required
string
integration
required
string
name
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "origin": "test",
  • "integration": "test",
  • "name": "test",
  • "body": "test"
}

Create integration for specified origin and name

Create integration for specified origin and name

path Parameters
origin
required
string
integration
required
string
name
required
string

Responses

Delete integration for specified origin and name

Delete integration for specified origin and name

path Parameters
origin
required
string
integration
required
string
name
required
string

Responses

Accept this invitation

Accept this invitation

Authorizations:
oauth_2_0
path Parameters
origin
required
string
invitationId
required
string

Responses

Rescind an invitation that hasn't already been ign

Rescind an invitation that hasn't already been ignored

Authorizations:
oauth_2_0
path Parameters
origin
required
string
invitationId
required
string

Responses

Ignore this invitation

Ignore this invitation

Authorizations:
oauth_2_0
path Parameters
origin
required
string
invitationId
required
string

Responses

List packages for an origin

List packages for an origin

path Parameters
origin
required
string
query Parameters
distinct
boolean
Default: false
Example: distinct=true

Whether to show a distinct list of packages or not

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List packages for a specified origin and package n

List packages for a specified origin and package name

path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Returns all versions and a count of releases for e

Returns all versions and a count of releases for each version for a given package

path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get latest package for specified origin and packag

Get latest package for specified origin and package

path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "owner_id": 2,
  • "ident": {
    }
}

Get packages with specified origin, package name,

Get packages with specified origin, package name, and version

path Parameters
origin
required
string
name
required
string
version
required
string

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get latest package with specified origin, package

Get latest package with specified origin, package name, and version

path Parameters
origin
required
string
name
required
string
version
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "owner_id": 2,
  • "ident": {
    }
}

Gets package for specified origin, package name, v

Gets package for specified origin, package name, version, and release

path Parameters
origin
required
string
name
required
string
version
required
string
release
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "owner_id": 2,
  • "ident": {
    }
}

Uploads a package

Uploads a package

path Parameters
origin
required
string
name
required
string
version
required
string
release
required
string

Responses

Deletes a package

Deletes a package

path Parameters
origin
required
string
name
required
string
version
required
string
release
required
string

Responses

Change the visibility of a package

Change the visibility of a package

path Parameters
name
required
string
version
required
string
origin
required
string
release
required
string
visibility
required
string

Responses

Downloads the package with specified origin, name,

Downloads the package with specified origin, name, version, and release

path Parameters
origin
required
string
name
required
string
version
required
string
release
required
string

Responses

Gets list of channels for this origin, package nam

Gets list of channels for this origin, package name, version, and release

path Parameters
origin
required
string
name
required
string
version
required
string
release
required
string

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Search for packages with a query string

Search for packages with a query string

path Parameters
query
required
string
query Parameters
distinct
boolean
Default: false
Example: distinct=true

Whether to show a distinct list of packages or not

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get schedule for specified group

Get schedule for specified group

path Parameters
groupid
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "state": "active",
  • "name": "jobsrv",
  • "project": "sample",
  • "target": "linux"
}

Get origin schedule status

Get origin schedule status

path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Schedule a job group

Schedule a job group

path Parameters
origin
required
string
pkg
required
string

Responses

Get local builder events

Get local builder events

query Parameters
nextRange
required
integer

Paginated index of next range to return

fromDate
required
string

From date to include in query results (inclusive)

toDate
required
string

To date to include in query results (inclusive)

query
required
string
Default: ""

Query parameters

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get SAAS builder events

Get SAAS builder events

query Parameters
nextRange
required
integer

Paginated index of next range to return

fromDate
required
string

From date to include in query results (inclusive)

toDate
required
string

To date to include in query results (inclusive)

query
required
string
Default: ""

Query parameters

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Notification of github events [ping, push]

Notification of github events [ping, push]

Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
null

List all channels for an origin

List all channels for an origin

path Parameters
origin
required
string

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a channel

Create a channel

path Parameters
origin
required
string
channel
required
string

Responses

Deletes a channel

Deletes a channel

path Parameters
origin
required
string
channel
required
string

Responses

List all packages in a channel

List all packages in a channel

path Parameters
origin
required
string
channel
required
string

Responses

Response samples

Content type
application/json
{
  • "range_start": 0,
  • "range_end": 49,
  • "total_count": 8,
  • "data": [
    ]
}

List latest packages in a channel, by target (requ

List latest packages in a channel, by target (required)

path Parameters
origin
required
string
channel
required
string

Responses

Response samples

Content type
application/json
{
  • "channel": "stable",
  • "target": "x86_64-linux",
  • "data": [
    ]
}

Promotes all packages in a channel queryParameters

Promotes all packages in a channel queryParameters

path Parameters
origin
required
string
channel
required
string

Responses

Demotes list of packages from a channel queryParam

Demotes list of packages from a channel queryParameters

path Parameters
origin
required
string
channel
required
string

Responses

List all packages in a channel that match the spec

List all packages in a channel that match the specified identifier

path Parameters
origin
required
string
channel
required
string
pkg
required
string

Responses

Response samples

Content type
application/json
{ }

Get the latest version of the package in this chan

Get the latest version of the package in this channel that matches the specified identifier

path Parameters
origin
required
string
channel
required
string
pkg
required
string

Responses

Response samples

Content type
application/json
{
  • "checksum": "7a998b6a756f7ca769ac75edf66c119d14aa911d7cfb5fd91ad3ff21ddf0d257",
  • "config": "",
  • "deps": [
    ],
  • "exposes": [ ],
  • "ident": {
    },
  • "manifest": "# core / tree\n\n\n* __Maintainer__: The Habitat Maintainers <humans@habitat.sh>\n* __Version__: 1.7.0\n* __Release__: 20161102210957\n* __Architecture__: x86_64\n* __System__: linux\n* __Target__: x86_64-linux\n* __Upstream URL__: upstream project's website or home page is not defined\n* __License__: gplv2+ \n* __Source__: [http://mama.indstate.edu/users/ice/tree/src/tree-1.7.0.tgz](http://mama.indstate.edu/users/ice/tree/src/tree-1.7.0.tgz)\n* __SHA__: `6957c20e82561ac4231638996e74f4cfa4e6faabc5a2f511f0b4e3940e8f7b12`\n* __Path__: `/hab/pkgs/core/tree/1.7.0/20161102210957`\n* __Build Dependencies__: `core/make core/gcc `\n* __Dependencies__: `core/glibc `\n* __Interpreters__: no interpreters or undefined\n\n# Plan\n\n## Build Flags\n\n```bash\nCFLAGS: -I/hab/pkgs/core/glibc/2.22/20160612063629/include -I/hab/pkgs/core/make/4.2.1/20161102154828/include -I/hab/pkgs/core/gcc/5.2.0/20161031031637/include\nCPPFLAGS: -I/hab/pkgs/core/glibc/2.22/20160612063629/include -I/hab/pkgs/core/make/4.2.1/20161102154828/include -I/hab/pkgs/core/gcc/5.2.0/20161031031637/include\nCXXFLAGS: -I/hab/pkgs/core/glibc/2.22/20160612063629/include -I/hab/pkgs/core/make/4.2.1/20161102154828/include -I/hab/pkgs/core/gcc/5.2.0/20161031031637/include\nLDFLAGS: -L/hab/pkgs/core/glibc/2.22/20160612063629/lib -L/hab/pkgs/core/gcc/5.2.0/20161031031637/lib\nLD_RUN_PATH: /hab/pkgs/core/tree/1.7.0/20161102210957/lib:/hab/pkgs/core/glibc/2.22/20160612063629/lib\n```\n\n## Plan Source\n\n```bash\npkg_name=tree\npkg_origin=core\npkg_version=1.7.0\npkg_maintainer=\"The Habitat Maintainers <humans@habitat.sh>\"\npkg_license=('gplv2+')\npkg_source=http://mama.indstate.edu/users/ice/tree/src/tree-${pkg_version}.tgz\npkg_shasum=6957c20e82561ac4231638996e74f4cfa4e6faabc5a2f511f0b4e3940e8f7b12\npkg_deps=(core/glibc)\npkg_build_deps=(core/make core/gcc)\npkg_bin_dirs=(bin)\npkg_include_dirs=(include)\npkg_lib_dirs=(lib)\n\ndo_build() {\n make\n}\n\ndo_install() {\n sed -i \"s#prefix = /usr#prefix = ${pkg_prefix}#\" Makefile\n make install\n}\n```",
  • "tdeps": [
    ]
}

List all packages in a channel that match the spec

List all packages in a channel that match the specified identifier and version

path Parameters
origin
required
string
channel
required
string
pkg
required
string
version
required
string

Responses

Response samples

Content type
application/json
{ }

Get the latest version of the package in this chan

Get the latest version of the package in this channel that matches the specified identifier and version

path Parameters
origin
required
string
channel
required
string
pkg
required
string
version
required
string

Responses

Response samples

Content type
application/json
{ }

Get the package in a channel that matches the spec

Get the package in a channel that matches the specified identifier, version and release

path Parameters
channel
required
string
pkg
required
string
version
required
string
origin
required
string
release
required
string

Responses

Response samples

Content type
application/json
{ }

Promote a package to a specific channel

Promote a package to a specific channel

path Parameters
channel
required
string
pkg
required
string
version
required
string
origin
required
string
release
required
string

Responses

Demote a package from a specific channel

Demote a package from a specific channel

path Parameters
channel
required
string
pkg
required
string
version
required
string
origin
required
string
release
required
string

Responses

Create new package settings entry

Create new package settings entry

Authorizations:
oauth_2_0
path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1234567890,
  • "origin": "xyz",
  • "name": "abc",
  • "visibility": "private",
  • "owner_id": 77730215748435970,
  • "created_at": "2017-05-05 00:42:35.213765+00",
  • "updated_at": "2017-05-05 00:42:35.213765+00"
}

Get package settings for top level package

Get package settings for top level package

Authorizations:
oauth_2_0
path Parameters
origin
required
string
name
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 1234567890,
  • "origin": "xyz",
  • "name": "abc",
  • "visibility": "private",
  • "owner_id": 77730215748435970,
  • "created_at": "2017-05-05 00:42:35.213765+00",
  • "updated_at": "2017-05-05 00:42:35.213765+00"
}

Update a package settings entry

Update a package settings entry

Authorizations:
oauth_2_0
path Parameters
origin
required
string
name
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "visibility": "private"
}

Response samples

Content type
application/json
{
  • "id": 1234567890,
  • "origin": "xyz",
  • "name": "abc",
  • "visibility": "private",
  • "owner_id": 77730215748435970,
  • "created_at": "2017-05-05 00:42:35.213765+00",
  • "updated_at": "2017-05-05 00:42:35.213765+00"
}

Delete a package settings entry

Delete a package settings entry

Authorizations:
oauth_2_0
path Parameters
origin
required
string
name
required
string

Responses