Chef Habitat API Documentation

Download OpenAPI specification:Download

E-mail: support@chef.io URL: https://www.chef.io/support/ License: Apache 2.0 Terms of Service

Authentication

oauth_2_0

Builder supports OAuth 2.0 for authenticating all API requests.

Security Scheme Type	OAuth2
implicit OAuth Flow	Authorization URL: https://{rootUri}/oauth2/authorize Scopes:

GET_status

Returns the health of the service

Responses

GET_authenticate-code

path Parameters

code

required

string

Responses

Response samples

200

Content type

application/json


{"token": "0b79bab50daca910b000d4f1a2b675d604257e42",
"email": "reset@chef.io",
"name": "reset",
"id": "73089155726360582",
"flags": 0
}

GET_ext-installations-install_id-repos-repo_id-contents-path

path Parameters

repo_id required	string
path required	string
install_id required	string

Responses

GET_profile

Retrieve your profile

Authorizations:

oauth_2_0

Responses

Response samples

200

Content type

application/json


{"id": 1234567890,
"name": "jimmy",
"email": "jimmy@example.com"
}

PATCH_profile

Update your profile

Authorizations:

oauth_2_0

Request Body schema: application/json

email

required

string

Responses

Request samples

Payload

Content type

application/json


{"email": "jimmy@example.com"
}

GET_profile-access-tokens

Retrieve your personal access tokens

Authorizations:

oauth_2_0

Responses

Response samples

200

Content type

application/json

""

POST_profile-access-tokens

Generate a new personal access token

Authorizations:

oauth_2_0

Request Body schema: application/json

string

Responses

Request samples

Payload

Content type

application/json

"string"

DELETE_profile-access-tokens

Delete (revoke) a personal access token

Authorizations:

oauth_2_0

Request Body schema: application/json

string

Responses

Request samples

Payload

Content type

application/json

"string"

POST_jobs

Create a new job for the given project

Authorizations:

oauth_2_0

Request Body schema: application/json

project_id

required

string

Responses

Request samples

Payload

Content type

application/json


{"project_id": "core/nginx"
}

Response samples

201

Content type

application/json


{"id": "73089155726360582",
"state": 0
}

POST_jobs-group-id-promote-channel

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

path Parameters

channel required	string
id required	string

Responses

GET_jobs-jobId

Get the status of the given job

path Parameters

jobId

required

string

Responses

Response samples

200

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_jobs-jobId-log

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 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

200

Content type

application/json

"{\n    \"start\": 0,\n    \"stop\": 2,\n    \"content\": [\n        \"this is the first line\",\n        \"this is the second line\"\n    ],\n    is_complete: false\n}\n"

GET_rdeps-origin-name

Retrieves the list of reverse dependencies for this package.

path Parameters

name required	string
origin required	string

Responses

Response samples

200

Content type

application/json


{"origin": "core",
"name": "linux-headers",
"rdeps": 
["core/redis"
]
}

GET_rdeps-origin-name-group

Retrieves the list of reverse dependencies for this package, collated into build groups that can be build in parallel

path Parameters

name required	string
origin required	string

Responses

Response samples

200

Content type

application/json


{"origin": "core",
"name": "linux-headers",
"rdeps": 
[
{"group": 0,
"idents": 
["core/redis",
"core/protobuf"
]
},
{"group": 1,
"idents": 
["core/node"
]
}
]
}

GET_user-invitations

Authorizations:

oauth_2_0

Responses

DELETE_user-invitationId

Authorizations:

oauth_2_0

path Parameters

invitationId

required

string

Responses

PUT_user-invitationId

Authorizations:

oauth_2_0

path Parameters

invitationId

required

string

Responses

GET_user-origins

Authorizations:

oauth_2_0

Responses

POST_projects

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

origin required	string
plan_path required	string
required	object

Responses

Request samples

Payload

Content type

application/json


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

Response samples

201

Content type

application/json


{"id": "habitat/builder-api",
"plan_path": "components/builder-api/plan.sh",
"vcs": 
{"type": "git",
"url": "https://github.com/habitat-sh/habitat.git"
}
}

GET_projects-origin-name

Return the project matching the given ID

path Parameters

origin required	string
name required	string

Responses

Response samples

200

Content type

application/json


{"id": "habitat/builder-api",
"plan_path": "components/builder-api/plan.sh",
"vcs": 
{"type": "git",
"url": "https://github.com/habitat-sh/habitat.git"
}
}

PUT_projects-origin-name

Update the project matching the given ID

Authorizations:

oauth_2_0

path Parameters

origin required	string
name required	string

Request Body schema: application/json

id required	string
plan_path required	string
required	object

Responses

Request samples

Payload

Content type

application/json


{"plan_path": "components/builder-api/plan.sh",
"github": 
{"organization": "habitat-sh",
"repo": "habitat"
}
}

DELETE_projects-origin-name

Destroys the project matching the given ID

Authorizations:

oauth_2_0

path Parameters

origin required	string
name required	string

Responses

PATCH_projects-origin-name-visibility

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

visibility required	string
origin required	string
name required	string

Responses

GET_projects-origin-name-jobs

Retrieve the most recently started jobs for the given project.

path Parameters

origin required	string
name required	string

Responses

Response samples

200

Content type

application/json


{"range_start": 0,
"range_end": 5,
"total_count": 6,
"data": 
[
{"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"
}
]
}

POST_origins

Create a new origin

Authorizations:

oauth_2_0

Request Body schema: application/json

id	integer
name	string
owner_id	string
default_package_visibility	string Enum: "Public" "Private"

Responses

Request samples

Payload

Content type

application/json


{"name": "reset",
"default_package_visibility": "public"
}

Response samples

200

Content type

application/json


{"id": "77732030103691265",
"name": "reset",
"owner_id": "77730215748435968",
"default_package_visibility": "public"
}

POST_origins-origin-users-username-invitations

Create an invitation to this origin for this user

Authorizations:

oauth_2_0

path Parameters

username required	string
origin required	string

Responses

GET_origins-origin-integrations

Get an object of all integrations

Authorizations:

oauth_2_0

path Parameters

origin

required

string

Responses

Response samples

200

Content type

application/json


{"docker": 
["region1",
"region2"
],
"google": 
["region3"
]
}

PUT_origins-origin-integrations-integrationName-default

Create or update an origin project integration

Authorizations:

oauth_2_0

path Parameters

integrationName required	string
origin required	string

Responses

Response samples

204

Content type

application/json


{"docker_hub_repo_name": "myorg/myrepo",
"custom_tag": "some-tag",
"latest_tag": true,
"version_tag": false,
"version_release_tag": true
}

DELETE_origins-origin-integrations-integrationName-default

Delete an origin project integration

Authorizations:

oauth_2_0

path Parameters

integrationName required	string
origin required	string

Responses

POST_origins-origin-transfer-user

Transfer ownership of origin to new origin member

Authorizations:

oauth_2_0

path Parameters

user required	string
origin required	string

Responses

POST_origins-origin-depart

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

Authorizations:

oauth_2_0

path Parameters

origin

required

string

Responses

PUT_origins-origin-invitations-invitationId

Accept this invitation

Authorizations:

oauth_2_0

path Parameters

invitationId required	string
origin required	string

Responses

DELETE_origins-origin-invitations-invitationId

Rescind an invitation that hasn't already been ignored

Authorizations:

oauth_2_0

path Parameters

invitationId required	string
origin required	string

Responses

PUT_origins-origin-invitations-invitationId-ignore

Ignore this invitation

Authorizations:

oauth_2_0

path Parameters

invitationId required	string
origin required	string

Responses

GET_origins-originId

path Parameters

originId

required

string

Request Body schema: application/json

id	integer
name	string
owner_id	string
default_package_visibility	string Enum: "Public" "Private"

Responses

Request samples

Payload

Content type

application/json

"{\n    \"id\": \"77732030103691265\",\n    \"name\": \"reset\",\n    \"owner_id\": \"77730215748435968\"\n    \"default_package_visibility\": \"public\"\n}\n"

GET_origins-originId-keys

Return a list of key revisions for an organization.

path Parameters

originId

required

string

Responses

Response samples

200

Content type

application/json


[
{"origin": "core",
"revision": "20160423193732",
"location": "/origins/core/keys/20160423193732"
},
{"origin": "core",
"revision": "20160423193733",
"location": "/origins/core/keys/20160423193733"
}
]

GET_origins-originId-keys-revision

Get a key revision for a specific origin

path Parameters

revision required	string
originId required	string

Responses

POST_origins-originId-keys-revision

Upload a new key revision for an origin

Authorizations:

oauth_2_0

path Parameters

revision required	string
originId required	string

Request Body schema: text/plain

string

Responses

Request samples

Payload

Content type

text/plain

SIG-PUB-1
core-20160423193745

Jpmj1gD9oTFCgz3wSLltt/QB6RTmNRWoUTe+xhDTIHc=

GET_origins-originId-secret_keys-latest

Retrieve the latest secret key

path Parameters

originId

required

string

Responses

Response samples

200

Content type

application/json


{"id": "",
"origin_id": "",
"name": "",
"revision": "",
"body": "",
"owner_id": ""
}

GET_origins-originId-encryption_key

Download public encryption key for origin responses

path Parameters

originId

required

string

Responses

POST_origins-originId-secret

upload a secret payload body

path Parameters

originId

required

string

Responses

GET_origins-originId-secret

Get a list of all secrets for your origin

path Parameters

originId

required

string

Responses

Response samples

200

Content type

application/json


[
{"key1": "value"
},
{"key2": "value"
}
]

DELETE_origins-originId-secret-secret

Delete a secret for an origin given a secret name

path Parameters

secret required	string
originId required	string

Responses

GET_origins-originId-users

List all members of an origin

path Parameters

originId

required

string

Responses

Response samples

200

Content type

application/json


{"members": 
["reset"
],
"origin_id": "77731431660388352"
}

GET_pkgs-search-query

Search for packages with a query string

path Parameters

query

required

string

query Parameters

distinct

boolean

Default: false

Whether to show a distinct list of packages or not

Responses

GET_pkgs-origin

List packages for an origin

path Parameters

origin

required

string

query Parameters

distinct

boolean

Default: false

Whether to show a distinct list of packages or not

Responses

GET_pkgs-origin-name

TODO

path Parameters

name required	string
origin required	string

Responses

GET_pkgs-origin-name-versions

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

path Parameters

name required	string
origin required	string

Responses

Response samples

200

Content type

application/json


[
{"origin": "core",
"name": "redis",
"version": "3.2.1",
"release_count": "3",
"latest": "20170215222111"
}
]

GET_pkgs-origin-name-latest

TODO

path Parameters

name required	string
origin required	string

Responses

GET_pkgs-origin-name-version

TODO

path Parameters

version required	string
name required	string
origin required	string

Responses

GET_pkgs-origin-name-version-latest

path Parameters

version required	string
name required	string
origin required	string

Responses

GET_pkgs-origin-name-version-release

path Parameters

release required	string
version required	string
name required	string
origin required	string

Responses

POST_pkgs-origin-name-version-release

path Parameters

release required	string
version required	string
name required	string
origin required	string

Responses

PATCH_pkgs-origin-name-version-release-visibility

Change the visibility of a package

path Parameters

visibility required	string
release required	string
version required	string
name required	string
origin required	string

Responses

GET_pkgs-origin-name-version-release-download

path Parameters

release required	string
version required	string
name required	string
origin required	string

Responses

GET_pkgs-origin-name-version-release-channels

path Parameters

release required	string
version required	string
name required	string
origin required	string

Responses

Response samples

200

Content type

application/json


["stable",
"unstable"
]

GET_channels-origin

List all channels for an origin

path Parameters

origin

required

string

Responses

Response samples

200

Content type

application/json


["stable",
"unstable"
]

POST_channels-origin-channel

Create a channel

path Parameters

channel required	string
origin required	string

Responses

DELETE_channels-origin-channel

Deletes a channel

path Parameters

channel required	string
origin required	string

Responses

GET_channels-origin-channel-pkgs

List all packages in a channel

path Parameters

channel required	string
origin required	string

Responses

Response samples

200

Content type

application/json


{"range_start": 0,
"range_end": 49,
"total_count": 8,
"data": 
[
{"origin": "core",
"name": "glibc",
"version": "2.22",
"release": "20160612063629"
},
{"origin": "core",
"name": "linux-headers",
"version": "4.3",
"release": "20160612063537"
}
]
}

POST_channels-origin-channel-pkgs-promote

Promotes all packages in a channel queryParameters

path Parameters

channel required	string
origin required	string

Responses

POST_channels-origin-channel-pkgs-demote

Demotes list of packages from a channel queryParameters

path Parameters

channel required	string
origin required	string

Responses

GET_channels-origin-channel-pkgs-pkg

List all packages in a channel that match the specified identifier

path Parameters

pkg required	string
channel required	string
origin required	string

Responses

GET_channels-origin-channel-pkgs-pkg-latest

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

path Parameters

pkg required	string
channel required	string
origin required	string

Responses

Response samples

200

Content type

application/json


{"checksum": "7a998b6a756f7ca769ac75edf66c119d14aa911d7cfb5fd91ad3ff21ddf0d257",
"config": "",
"deps": 
[
{"name": "glibc",
"origin": "core",
"release": "20160612063629",
"version": "2.22"
}
],
"exposes": [ ],
"ident": 
{"name": "tree",
"origin": "core",
"release": "20161102210957",
"version": "1.7.0"
},
"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": 
[
{"name": "glibc",
"origin": "core",
"release": "20160612063629",
"version": "2.22"
},
{"name": "linux-headers",
"origin": "core",
"release": "20160612063537",
"version": "4.3"
}
]
}

GET_channels-origin-channel-pkgs-pkg-version

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

path Parameters

version required	string
pkg required	string
channel required	string
origin required	string

Responses

GET_channels-origin-channel-pkgs-pkg-version-latest

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

path Parameters

version required	string
pkg required	string
channel required	string
origin required	string

Responses

GET_channels-origin-channel-pkgs-pkg-version-release

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

path Parameters

release required	string
version required	string
pkg required	string
channel required	string
origin required	string

Responses

PUT_channels-origin-channel-pkgs-pkg-version-release-promote

Promote a package to a specific channel

path Parameters

release required	string
version required	string
pkg required	string
channel required	string
origin required	string

Responses

PUT_channels-origin-channel-pkgs-pkg-version-release-demote

Demote a package from a specific channel

path Parameters

release required	string
version required	string
pkg required	string
channel required	string
origin required	string