Introduction
Overview
Welcome to the Cloud Foundry V3 API docs! Version 3 adds support for several key features:
- Running one-off tasks on Cloud Foundry
- Applications consisting of several processes via a Procfile
- Direct access to application packages and droplets
- Changing application source code without stopping the app via deployments
Getting help
The CAPI team can most easily be reached on our Slack channel for questions and issues regarding the API. To report an issue with the docs or API, please feel free to file a GitHub issue on our API repo, cloud_controller_ng.
We recommend reaching out to Slack first as we will be most responsive there.
More resources
- The Cloud Foundry V2 API is still available for interacting with Cloud Foundry.
- Running Tasks
- V3 API Documentation Source Code
Concepts
API Resource
A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object.
A resource consists of several required resource fields and other attributes specific to the resource.
See Resources and Experimental Resources for specific resources.
Required fields
Example Person Resource
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "Bob",
"links": {
"self": {
"href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | The unique identifier for the resource |
created_at | timestamp | The ISO8601 compatible date and time when resource was created |
updated_at | timestamp | The ISO8601 compatible date and time when resource was last updated |
links | links object | URLs to related resources and actions for the current resource |
Links
Links provide URLs to relationships and actions for a resource. Links are represented as a JSON object and always contain a self
link.
Each link is keyed by its type and will include a href
for the URL and an optional method
for links that cannot be followed using GET
.
The link object
Example Link object
{
"href": "http://example.com/some/endpoint",
"method": "POST"
}
Name | Type | Description |
---|---|---|
href | string | The absolute URL |
method | string | An optional field containing the HTTP method to be used when following the URL |
Authentication
The Cloud Foundry V3 API is secured using OAuth 2. Clients are expected to present a valid bearer token via HTTP header: Authorization: bearer <token>
Tokens can be obtained from the Cloud Foundry UAA server. For more information, see the UAA API Documentation
Authorization
Access to resources is determined by combining scopes in the OAuth 2 token with user roles that are managed by the API.
OAuth 2 scopes
Scope | Description |
---|---|
cloud_controller.admin |
This scope provides read and write access to all resources |
cloud_controller.admin_read_only |
This scope provides read only access to all resources |
cloud_controller.global_auditor |
This scope provides read only access to all resources except secrets (such as environment variables) |
cloud_controller.read |
This scope provides read access to resources based on user roles |
cloud_controller.write |
This scope provides write access to resources based on user roles |
cloud_controller.update_build_state |
This scope allows its bearer to update the state of a build; currently only used when updating builds |
cloud_controller_service_permissions.read |
This scope provides read only access for service instance permissions |
Cloud Foundry user roles
Users that interact with the API should have one or more of these roles. Some of them (e.g. admin) are controlled via scopes on the user’s token. Others (e.g. space developer) are controlled via the roles resource.
Role | Description |
---|---|
Admin | Allows a user to manage the platform; OAuth token must contain cloud_controller.admin scope |
Admin Read-Only | Allows a user to read all resources on the platform; OAuth token must contain cloud_controller.admin_read_only scope |
Global Auditor | Allows a user to read all resources on the platform, excluding sensitive data such as environment variables and service bindings. OAuth token must contain cloud_controller.global_auditor scope |
Org User | Allows a user to be assigned other roles within an organization and its spaces |
Org Manager | Provides organization management access |
Org Auditor | Provides read-only access to an organization for auditing purposes |
Org Billing Manager | Allows a user to create and manage billing account and payment information |
Space Developer | Allows developers to create and manage apps and services in a space |
Space Manager | Provides space management access |
Space Auditor | Provides read-only access to a space for auditing purposes |
Space Supporter | Troubleshoot and debug apps and service bindings in a space |
Component roles
Components that interact with the Cloud Controller in the back-end can be given these roles to allow limited access to API resources. These roles are controlled via scopes on the component’s token.
Role | Description |
---|---|
Build State Updater | Allows a component to update the state of build resources; OAuth token must contain cloud_controller.update_build_state scope |
Errors
Example Error
{
"errors": [
{
"code": 10008,
"title": "CF-UnprocessableEntity",
"detail": "something went wrong"
}
]
}
An error response will always return a list of error objects. Errors appear on the job resource for asynchronous operations.
The error object
Clients should use the code
and title
fields for programmatically handling specific errors.
The message in the detail
field is subject to change over time.
Name | Type | Description |
---|---|---|
code | integer | A numeric code for this error |
title | string | Name of the error |
detail | string | Detailed description of the error |
Common errors
These are some of the more common errors returned by many endpoints.
Title | Code | HTTP Status | Description |
---|---|---|---|
CF-BadQueryParameter |
10005 | 400 | An invalid query parameter was given |
CF-InvalidAuthToken |
1000 | 401 | An invalid auth token was given |
CF-NotAuthenticated |
10002 | 401 | No auth token was given, but authentication is required for this endpoint |
CF-NotAuthorized |
10003 | 403 | The authenticated user does not have permission to perform this operation |
CF-ResourceNotFound |
10010 | 404 | The specified resource does not exist, or the authenticated user cannot read it |
CF-UnprocessableEntity |
10008 | 422 | Catch-all error when an operation fails to complete; the detail field will contain more information |
UnknownError |
10001 | 500 | An unexpected, uncaught error occurred; the CC logs will contain more information |
Fields
The fields
parameter allows clients to fetch resources and include information of parent objects
in the response. It works in a similar way to include, but the response only displays
the requested fields rather than the entire resource.
For example, a response to /v3/service_instances/:guid?fields[space.organization]=name
will contain detailed
information about the service instance, as well as the name of the organization it belongs to.
Developers may choose to use the fields
feature to reduce the number of API calls. The fields
query param can be used with a single resource or a list of resources.
The fields query parameter may also grant visibility to parts of resources where the whole resource is not visible. For instance, the name of an organization may be retrieved with fields, where the whole organization resource may not be visible.
Fields parameter
The fields parameter is structured as: fields[resource]=keys&fields[parent.resource]=other,keys
resource
is the name of the resource being requested, qualified by the relationship to the current resource. For example/v3/service_instances?fields[space]=name
wherespace
is a direct relationship of a service instance, or/v3/service_instances?fields[space.organization]=name
whereorganization
is a relationship ofspace
.keys
is a comma-separated list of the fields in the object being requested. For example,/v3/service_instances?fields[space]=name,guid
will return just thename
andguid
of the space in the includes section.
For information on fields
support for each resource refer to its documentation.
Resources with Fields
Resource | Endpoint |
---|---|
Service Instances | v3/service_instances, v3/service_instances/:guid |
Shared Spaces | /v3/service_instances/:guid/relationships/shared_spaces |
Service Offerings | v3/service_offerings, v3/service_offerings/:guid |
Service Plans | v3/service_plans, v3/service_plans/:guid |
Fields Sample requests
Example request to service instances resource to include parent orgs and spaces
curl "https://api.example.org/v3/service_instances?fields[space]=name,guid,relationships.organization&fields[space.organization]=name,guid" \
-X GET \
-H "Authorization: bearer [token]"
Example response
{
"pagination": {
"total_results": 2,
"...": "..."
},
"resources": [
{
"guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
"name": "service_instance_1",
"...": "..."
},
{
"guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
"name": "service_instance_2",
"...": "..."
}
],
"included": {
"spaces": [
{
"guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
"name": "space1",
"relationships": {
"organization": {
"data": {
"guid": "b2075a71-28b6-411a-a896-56f75d892f58"
}
}
}
},
{
"guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
"name": "space2",
"relationships": {
"organization": {
"data": {
"guid": "b56fbd01-296b-442b-8faf-a559aebf985e"
}
}
}
}
],
"organizations": [
{
"guid": "b2075a71-28b6-411a-a896-56f75d892f58",
"name": "org1"
},
{
"guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
"name": "org2"
}
]
}
}
Filters
Endpoints which return lists of resources also support filtering the returned resources using query parameters. Each resource’s list endpoint documents the allowed filters for that endpoint. For details about the syntax of query parameters in general, see query parameters.
Examples
Single value request
GET /v3/apps?names=the_name
This will return all apps with name the_name
.
Multiple value request
GET /v3/apps?names=first_name,second_name
This will return all apps with name the_name
OR second_name
.
In the case of audit events, multiple timestamps can be requested, which will return all audit events that occurred at those timestamps. In the following request, all audit events that occurred New Year’s just before midnight and July 4th at noon will be returned:
GET /v3/audit_events?created_ats=2019-12-31T23:59:59Z,2020-07-04T12:00:00Z
Exception
The label_selector
query parameter will act as AND function, not an OR.
GET /v3/spaces?label_selector=production,east_coast
This will return all spaces whose metadata has labels with keys production
AND east_coast
.
Combined filters
GET /v3/apps?names=the_name&stacks=cflinuxfs4
This will return all apps with name the_name
AND stack cflinuxfs4
.
Empty filters
An empty filter (/v3/resources?fields=
) can mean either empty string (""
) or NULL
, depending on the resource type.
GET /v3/buildpacks?stacks=
This will return all buildpacks with stack NULL
.
GET /v3/routes?hosts=hostname1,,hostname2
This will return all routes with hostname "hostname1"
, ""
OR "hostname2"
.
Relational Operators
Some fields (e.g. created_at
and updated_at
) can be filtered using relational operators when listing resources.
For example, a response to GET /v3/audit_events?created_ats[lt]=2020-06-30T12:34:56Z
will contain
audit events with a created_at
timestamp strictly earlier than 2020-06-30T12:34:56Z
.
Multiple relational operators can be combined to further refine the listed resources. For example, a
response to GET /v3/audit_events?created_ats[lt]=2020-01-02T00:00:00Z&created_ats[gt]=2019-12-31T23:59:59Z
will return all audit events occurring on New Year’s Day.
Timestamps must be in standard timestamp format.
Valid relational operators
Operator | Description |
---|---|
lt | Return resources strictly less than the given value for the filtered attribute |
lte | Return resources less than or equal to the given value for the filtered attribute |
gt | Return resources strictly greater than the given value for the filtered attribute |
gte | Return resources greater than or equal to the given value for the filtered attribute |
Exclusion Operator
Some fields support filtering on all values except a given set of values.
For example, a response to GET /v3/audit_events?target_guids[not]=guid-1,guid-2
will contain audit events with a target.guid
not equal to guid-1
nor guid-2
.
Operator | Description |
---|---|
not | Return resources not equal to the given value(s) for the filtered attribute |
Include
The include
parameter allows clients to fetch resources and include information of parent objects in the response.
For example, a response to /v3/spaces/:guid?include=organization
will contain detailed information about the space and its parent organization.
Developers may choose to use the include
feature to reduce the number of API calls. The include
query param can be used with a single resource or a list of resources.
Resources with includes
The following resources can take an include
parameter:
Resource | Allowed values |
---|---|
apps | space.organization , space |
apps/[:guid] | space.organization , space |
roles | user , space , organization |
roles/[:guid] | user , space , organization |
routes | domain , space.organization , space |
routes/[:guid] | domain , space.organization , space |
service_plans | space.organization , service_offering |
service_plans/[:guid] | space.organization , service_offering |
service_credential_bindings | app , service_instance |
service_credential_bindings/[:guid] | app , service_instance |
service_route_bindings | route , service_instance |
service_route_bindings/[:guid] | route , service_instance |
spaces | organization |
spaces/[:guid] | organization |
Sample requests
Example request to apps resource to include parent orgs and spaces
curl "https://api.example.org/v3/apps?include=space.organization" \
-X GET \
-H "Authorization: bearer [token]"
Example response
{
"pagination": {
"total_results": 2,
"...": "..."
},
"resources": [
{
"guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
"name": "app1",
"...": "..."
},
{
"guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
"name": "app2",
"...": "..."
}
],
"included": {
"spaces": [
{
"guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
"name": "space1",
"...": "..."
},
{
"guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
"name": "space2",
"...": "..."
}
],
"organizations": [
{
"guid": "b2075a71-28b6-411a-a896-56f75d892f58",
"name": "org1",
"...": "..."
},
{
"guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
"name": "org2",
"...": "..."
}
]
}
}
Example request for a single app instance to include its parent space
curl "https://api.example.org/v3/apps/[guid]?include=space" \
-X GET \
-H "Authorization: bearer [token]"
Example response
{
"guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
"name": "staticfile",
"...": "...",
"included": {
"spaces": [
{
"guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
"name": "space1a",
"...": "..."
}
]
}
}
Lifecycles
Lifecycles inform the platform of how to build droplets and run apps. For example, a docker
lifecycle will
pull a Docker image from a registry to run an app.
The lifecycle object
Name | Type | Description |
---|---|---|
type | string | Type of the lifecycle; valid values are buildpack , docker |
data | object | Data that is used during staging and running for a lifecycle |
Buildpack lifecycle
Example Buildpack Lifecycle
{
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
}
This is the default lifecycle for Cloud Foundry for VMs. When staging an app with this lifecycle, the app source code will be compiled using a buildpack, resulting in a droplet. When running an app with this lifecycle, a container running a rootfs will be created and the droplet will be expanded inside that container to be executed.
If buildpacks are not specified, then Cloud Foundry will automatically detect a compatible buildpack, based on the files in an app’s package. If a stack is not specified, then the app will default to the operator-configured default stack.
Buildpack lifecycle object
Name | Type | Description |
---|---|---|
type | string | buildpack |
data.buildpacks | list of strings | A list of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack during staging |
data.stack | string | The root filesystem to use with the buildpack, for example cflinuxfs4 |
Docker lifecycle
Example Docker Lifecycle
{
"type": "docker",
"data": {}
}
This allows Cloud Foundry to run pre-built Docker images. When staging an app with this lifecycle, the Docker registry is queried for metadata about the image, such as ports and start command. When running an app with this lifecycle, a container is created and the Docker image is executed inside of it.
Docker lifecycle object
Name | Type | Description |
---|---|---|
type | string | docker |
data | object | Data is not used by the Docker lifecycle; valid value is {} |
Metadata
Metadata allows you to tag API resources with information that does not directly affect its functionality.
Annotations
Example Resource with Annotations
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "api-server",
"metadata": {
"labels": {},
"annotations": {
"contacts": "Bill tel(1111111) email(bill@fixme), Bob tel(222222) pager(3333333#555) email(bob@fixme)"
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
}
}
}
Annotations are user-specified key-value pairs that are attached to API resources. They do not affect the operation of Cloud Foundry. Annotations cannot be used in filters.
When a service instance is being created, the service broker is sent the annotations of the service instance, and the space and organization in which the service instance resides.
When a service instance is being updated, the service broker is sent the annotations of the space and organization in which the service instance resides.
When a service binding is being created, the service broker is sent annotations of any associated app, and the space and organization in which the binding resides.
Only annotations with a prefix (e.g. company.com/contacts
) are sent to service brokers.
Examples may include (but are not limited to):
"contact info": "[email protected] [email protected]"
"library versions": "Spring: 5.1, Redis Client: a184098. yaml parser: 38"
"git-sha": "d56fe0367554ae5e878e37ed6c5b9a82f5995512"
Annotation keys
Annotation keys are made up of an (optional) prefix and name. If a prefix is present, it is separated from the name by a /
.
Prefixes are DNS names intended to enable namespacing of annotation keys.
An annotation key prefix
must adhere to the following restrictions:
- Length: 0-253 characters
- Allowed characters: a-z, A-Z, 0-9,
-
, and.
; emojis cannot be used in keys - DNS subdomain format (series of subdomain annotations separated by
.
)
An annotation key name
must adhere to the following restrictions:
- Length: 1-63 characters
- Allowed characters: a-z, A-Z, 0-9,
-
,_
, and.
; emojis cannot be used in keys - Must begin and end with an alphanumeric character
Annotation values
Annotation values must adhere to the following restrictions:
- Length: 0-5000 unicode characters
Labels and selectors
Example Resource with Labels
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "api-server",
"metadata": {
"labels": {
"environment": "production",
"internet-facing": "false"
},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
}
}
}
Labels are user-specified key/value pairs that are attached to API Resources. They are queryable, identifying attributes of a resource, but they do not affect the operation of CloudFoundry.
For example, an app may be assigned a label with key sensitive
and possible values true
or false
.
Users could then find all sensitive apps with a selector for sensitive=true
, resulting in a response containing
only apps having the label key sensitive
with a label value of true
.
Labels
Labels allow users to apply identifying attributes to resources that are meaningful to the user, but not the CloudFoundry system.
Examples may include (but are not limited to):
"production" : "true"
or"production" : "false"
"env" : "dev"
or"env" : "test"
or"env" : "prod"
"chargeback-code" : "abc123"
Label keys
Label keys are made up of an (optional) prefix, and name. If a prefix is present, it is separated from the name by a /
.
Prefixes are dns names intended to enable namespacing of label keys.
A label key prefix
must adhere to the following restrictions:
- Length: 0-253 characters
- Allowed characters: alphanumeric ( [a-z0-9A-Z] ),
-
, and.
- DNS subdomain format (series of subdomain labels separated by
.
)
A label key name
must adhere to the following restrictions:
- Length: 1-63 characters
- Allowed characters: alphanumeric ( [a-z0-9A-Z] ),
-
,_
, and.
- Must begin and end with an alphanumeric character
Label values
Label values must adhere to the following restrictions:
- Length: 0-63 characters
- Allowed characters: alphanumeric ( [a-z0-9A-Z] ),
-
,_
, and.
- Must begin and end with an alphanumeric character
- Empty values are allowed
Selectors
Example label selector
cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29
Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or
more requirements
in a comma-delimited list. The maximum number of requirements
in a single selector is 50.
eg: env=dev,!chargeback-code,tier in (backend,worker)
Selectors can be used to filter and group resources using the query parameter label_selector
on list endpoints.
A requirement consists of a key, an operator
, and optional value(s).
Requirement | Format | Description |
---|---|---|
existence | key | Returns all resources that have been assigned a label with the given key (with any value) |
non-existence | ! key |
Returns all resources that have not been assigned a label with the given key (with any value) |
equality | key= value or key== value |
Returns all resources that have been assigned a label with the given key and value |
inequality | key!= value |
Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value |
set inclusion | key in (value1,value2…) |
Returns all resources that have been assigned a label with the given key with one of the specified value(s) |
set exclusion | key notin (value1,value2…) |
Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s) |
See the metadata documentation for more information.
Updating labels and annotations
Example Initial Metadata
{
"metadata": {
"labels": {
"environment": "staging",
"ready-to-deploy": "true"
},
"annotations": {
"spring-version": "5.1",
"app-version": "0.1-alpha"
}
}
}
Example Patch Request Body
{
"metadata": {
"labels": {
"environment": "production",
"ready-to-deploy": null
},
"annotations": {
"app-version": "0.1",
"deployed-month": "november"
}
}
}
Example Final Metadata
{
"metadata": {
"labels": {
"environment": "production"
},
"annotations": {
"spring-version": "5.1",
"app-version": "0.1",
"deployed-month": "november"
}
}
}
Labels and annotations can be updated by using the PATCH endpoint for their resource. For example, to update labels or annotations on an app, use the update an app endpoint. When patching metadata, CAPI endpoints do a deep merge, only updating labels or annotations that are specified in the request.
Labels and annotations follow the same rules for patching and must be wrapped in the metadata object inside the request body
- To create, include the new key with a value
- To change, include the existing key with a new value
- To delete, include the existing key with a
null
value - To remain unchanged, do not include the existing key.
Pagination
Example Paginated Response
{
"pagination": {
"total_results": 3,
"total_pages": 3,
"first": {
"href": "https://api.example.org/v3/people?page=1&per_page=1"
},
"last": {
"href": "https://api.example.org/v3/people?page=3&per_page=1"
},
"next": {
"href": "https://api.example.org/v3/people?page=2&per_page=1"
},
"previous": null
},
"resources": [
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "Bob",
"links": {
"self": {
"href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
}
}
}
]
}
Any request that can return multiple resources will be paginated and contain a pagination
object and list of resources
.
Requests for multiple resources can use page
, per_page
, and order_by
in addition to filters specific to the endpoint.
The pagination object
Name | Type | Description |
---|---|---|
total_results | integer | Total number of resources for all pages |
total_pages | integer | Total number of pages |
first | link object | Link to the first page |
last | link object | Link to the last page |
next | link object | Link to the next page |
previous | link object | Link to the previous page |
Procfiles
Example Ruby Procfile
web: bundle exec rackup config.ru -p $PORT
rake: bundle exec rake
worker: bundle exec rake workers:start
A Procfile enables you to declare required runtime processes, called process types, for your app.
Procfiles must be named Procfile
exactly and placed in the root directory of your application.
In a Procfile, you declare one process type per line and use the syntax PROCESS_TYPE: COMMAND
.
PROCESS_TYPE
defines the type of the process.COMMAND
is the command line to launch the process.
Procfile use cases
Many buildpacks provide their own process types and commands by default; however, there are special
cases where specifying a custom COMMAND
is necessary. Commands can be overwritten by providing a
Procfile with the same process type.
For example, a buildpack may provide a worker
process type that runs the rake default:start
command. If a Procfile is provided that also contains a worker
process type, but a different
command such as rake custom:start
, the rake custom:start
command will be used.
Some buildpacks, such as Python, that work on a variety of frameworks, do not attempt to provide a default start command. For these cases, a Procfile should be used to specify any necessary commands for the app.
Web process
web
is a special process type that is required for all applications.
The web
PROCESS_TYPE
must be specified by either the buildpack or the Procfile.
Specifying processes in manifest files
Custom process types can also be configured via a manifest file. Read more about manifests. It is not recommended to specify processes in both a manifest and a Procfile for the same app.
Query Parameters
Clients can assume that query parameters on the API will always follow these rules:
- Parameter names (before the
=
, and ignoring any modifiers like[gt]
) will only contain charactersa-z
(lowercase) and-
. - When a parameter accepts multiple values, these will be represented as a comma-delimited list of strings (see filters).
Because commas are used to separate list entries, parameter values that contain commas must be percent-encoded. For example, to retrieve apps named either a,b
or c,d
, the query parameter would look like names=a%2Cb,c%2Cd
. Note that the commas within the app names are encoded (as %2C
), but the comma separating the two app names is not. The resulting query parameter must be encoded a second time before sending it to the API, e.g. cf curl /v3/apps?names=a%252Cb,c%252Cd
.
Relationships
Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not.
Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not.
Not all resources implement every relationship operation demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships.
Endpoints that return relationship data list this information under the relationships
key.
The relationship object
The relationship object is a key-value pair that uniquely identifies a resource. In practice this is
almost always the guid
of a resource.
Name | Type | Description |
---|---|---|
guid | string | The unique identifier for the related resource |
To-one relationships
Example to-one relationship
{
"data": {
"guid": "[related-resource-guid]"
}
}
Some relationships relate a resource to exactly one other resource. For example an app can belong to only one space.
To-one relationship object
Name | Type | Description |
---|---|---|
data | relationship object | A single relationship |
Setting the to-one relationship while creating an object
curl "https://api.example.org/v3/books" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"color": "yellow",
"relationships": {
"publisher": {
"data": {
"guid": "publisher-guid"
}
}
}
}'
Modifying the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"data": {
"guid": "publisher-guid"
}
}'
Removing the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{ "data": null }'
Viewing the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
-X GET \
-H "Authorization: bearer [token]"
To-many relationships
Example to-many relationship
{
"data": [
{ "guid": "[related-resource-guid-1]" },
{ "guid": "[related-resource-guid-2]" }
]
}
Some relationships relate a resource to several other resources. For example, an isolation segment can be entitled to multiple organizations.
To-many relationship object
Name | Type | Description |
---|---|---|
data | array of relationship objects | An array of multiple relationships |
Adding related to-many resources
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"data": [
{ "guid":"author-guid-1" },
{ "guid":"author-guid-2" }
]
}'
Replacing all to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"data": [
{ "guid":"author-guid-3" },
{ "guid":"author-guid-4" }
]
}'
Removing all to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{ "data": [] }'
Removing specific to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors/[author-guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Viewing the to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
-X GET \
-H "Authorization: bearer [token]"
Status Codes
Cloud Foundry V3 API uses a subset of HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that can potentially be fixed by correcting the request, and codes in the 5xx range indicate an error on the server side.
HTTP Status Code | Description |
---|---|
200 OK | The request completed successfully |
201 Created | The request completed successfully and created a new resource |
202 Accepted | The request will be completed asynchronously; see asynchronous operations |
204 No Content | The request completed successfully and did not return a body |
400 Bad Request | The request has malformed or invalid data |
401 Unauthenticated | The request requires an authenticated user |
403 Forbidden | The request cannot be performed by the user |
404 Not Found | The requested resource does not exist |
422 Unprocessable Entity | The request cannot be performed |
500 Internal Server Error | An unexpected error occurred |
502 Bad Gateway | An external upstream service caused the request to fail |
503 Service Unavailable | An internal upstream service caused the request to fail |
Timestamps
Timestamps generally appear in created_at
and updated_at
fields on resources. Precision beyond
seconds is not supported, even if the underlying database supports it (e.g. Postgres). As a result,
filtering on sub-second timestamps is not allowed.
All v3 timestamps have the following format YYYY-MM-DDThh:mm:ssZ
.
Example timestamp (June 30, 2020 at 11:49:04 PM UTC): 2020-06-30T23:49:04Z
Updating Actual State
The Cloud Controller is primarily responsible for the desired state of apps and processes. Most endpoints will only update the desired states of your apps and processes within Cloud Controller in order to provide users with the opportunity to incur zero downtime when updating apps. Restarting the app will be required for the desired state changes to become the actual state.
The stats endpoint can be used at any time to determine the actual (running) state of a process, and by proxy, an app.
Endpoints that will affect runtime
The following endpoints will immediately impact the runtime of the app, and the desired changes will take effect without needing to restart the app.
Endpoint |
---|
PATCH /v3/spaces/:guid/features/ssh |
DELETE /v3/routes/:guid/destinations/:destination_guid |
The following endpoints will immediately impact runtime and take effect when only the instances
field is updated. If any other fields are updated, the app will need to be restarted in order for any desired changes to take effect, including instance count changes.
Endpoint |
---|
POST /v3/processes/:guid/actions/scale |
POST /v3/apps/:guid/processes/:type/actions/scale |
The following endpoints will immediately impact runtime and the desired changes will take effect if the specified fields are not included in the request.
If the field is specified, the app will need to be restarted in order for any desired changes to take effect.
Endpoint | Changes requiring a restart |
---|---|
POST /v3/routes/:guid/destinations |
Adding a destination with a port |
PATCH /v3/routes/:guid/destinations |
Replacing the port field Note: If the port is specified, this endpoint will unmap any route not listed in the body but will not map any of the new routes in the request body. For this reason we caution against using the endpoint in most circumstances. A combination of adding ports and removing ports will better fit most use cases. |
All other changes will not take effect on running apps until they are restarted.
Warnings
Example Warnings
{
"warnings": [
{
"detail": "something went wrong"
}
]
}
Warnings appear on the job resource.
The warning object
Name | Type | Description |
---|---|---|
detail | string | Description of the warning |
Resources
Admin
These endpoints are only for admin users.
Clear buildpack cache
Example Request
curl "https://api.example.org/v3/admin/actions/clear_buildpack_cache" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
This endpoint will delete all of the existing buildpack caches in the blobstore. The buildpack cache is used during staging by buildpacks as a way to cache certain resources, e.g. downloaded Ruby gems. An admin who wants to decrease the size of their blobstore could use this endpoint to delete unnecessary blobs.
Definition
POST /v3/admin/actions/clear_buildpack_cache
Permitted roles
Admin |
Apps
Apps are top-level objects that link together and contain configuration information for your packages, droplets, processes, tasks, and more.
The app object
Example App object
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STOPPED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-06-08T16:41:26Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
},
"features": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the app |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
name | string | Name of the app |
state | string | Current desired state of the app; valid values are STOPPED or STARTED |
lifecycle | lifecycle object | Provides the default lifecycle object for the application. This lifecycle will be used when staging and running the application. The staging lifecycle can be overridden on builds |
relationships.space | to-one relationship | The space the app is contained in |
metadata.labels | label object | Labels applied to the app |
metadata.annotations | annotation object | Annotations added to the app |
links | links object | Links to related resources |
Create an app
Example Request
curl "https://api.example.org/v3/apps" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "my_app",
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STOPPED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-06-08T16:41:26Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
},
"features": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
POST /v3/apps
Required parameters
Name | Type | Description |
---|---|---|
name | string | Name of the app |
relationships.space | to-one relationship | A relationship to a space |
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
environment_variables | object | Environment variables to be used for the App when running | {} |
lifecycle | lifecycle object | Provides the lifecycle object for the application | buildpack lifecycle |
metadata.labels | label object | Labels applied to the app | |
metadata.annotations | annotation object | Annotations applied to the app |
Potential errors (experimental)
In addition to any common errors, this endpoint may return the following errors.
Title | Code | HTTP Status | Description |
---|---|---|---|
CF-UniquenessError |
10016 | 422 | The given app name is already taken in the targeted space |
CF-FeatureDisabled |
330002 | 403 | Some feature flag must be enabled by the Cloud Foundry admin in order to push the app as is. The detail message should contain information on which feature is disabled. |
Permitted roles
Admin |
Space Developer |
Get an app
Example Request
curl "https://api.example.org/v3/apps/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STOPPED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-06-08T16:41:26Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
},
"features": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
GET /v3/apps/:guid
Query parameters
Name | Type | Description |
---|---|---|
include | list of strings | Optionally include additional related resources in the response; valid values are space and space.organization |
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
List apps
Example Request
curl "https://api.example.org/v3/apps" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 3,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/apps?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/apps?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/apps?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STARTED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
},
"features": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "02b4ec9b-94c7-4468-9c23-4e906191a0f8",
"name": "my_app2",
"state": "STOPPED",
"created_at": "1970-01-01T00:00:02Z",
"updated_at": "2016-06-08T16:41:26Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["ruby_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed"
},
"features": {
"href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve all apps the user has access to.
Definition
GET /v3/apps
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of app guids to filter by |
names | list of strings | Comma-delimited list of app names to filter by |
space_guids | list of strings | Comma-delimited list of space guids to filter by |
organization_guids | list of strings | Comma-delimited list of organization guids to filter by |
stacks | list of strings | Comma-delimited list of stack names to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at , updated_at , name , state |
label_selector | string | A query string containing a list of label selector requirements |
lifecycle_type | string | Lifecycle type to filter by; valid values are buildpack , docker |
include | list of strings | Optionally include a list of unique related resources in the response; valid values are space and space.organization |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
Update an app
Example Request
curl "https://api.example.org/v3/apps/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "my_app",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"]
}
}
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STARTED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
},
"features": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
PATCH /v3/apps/:guid
Optional parameters
Name | Type | Description |
---|---|---|
name | string | Name of the app |
lifecycle | lifecycle object | Lifecycle to be used when updating the app; note: data is a required field in lifecycle if lifecycle is updated |
metadata.labels | label object | Labels applied to the app |
metadata.annotations | annotation object | Annotations applied to the app |
Permitted roles
Admin |
Space Developer |
Delete an app
Example Request
curl "https://api.example.org/v3/apps/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Definition
DELETE /v3/apps/:guid
Permitted roles
Admin |
Space Developer |
Get current droplet
Example Request
curl "https://api.example.org/v3/apps/[guid]/droplets/current" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"checksum": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpacks": [
{
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14",
"version": "1.1.1.",
"buildpack_name": "ruby"
}
],
"stack": "cflinuxfs4",
"image": null,
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"package": {
"href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
},
"download": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
GET /v3/apps/:guid/droplets/current
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Get current droplet association for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/relationships/current_droplet" \
-X GET \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet"
},
"related": {
"href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/droplets/current"
}
}
}
This endpoint retrieves the current droplet relationship for an app.
Definition
GET /v3/apps/:guid/relationships/current_droplet
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Get environment for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/env" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"staging_env_json": {
"GEM_CACHE": "http://gem-cache.example.org"
},
"running_env_json": {
"HTTP_PROXY": "http://proxy.example.org"
},
"environment_variables": {
"RAILS_ENV": "production"
},
"system_env_json": {
"VCAP_SERVICES": {
"mysql": [
{
"name": "db-for-my-app",
"binding_id": "0e85b634-e043-4b43-96da-f83dfe83ab33",
"binding_name": "db-for-my-app",
"instance_id": "07fca01c-f789-4d45-80b4-e19ba3ca862c",
"instance_name": "my-mysql-service",
"label": "mysql",
"tags": ["relational", "sql"],
"plan": "xlarge",
"credentials": {
"username": "user",
"password": "top-secret"
},
"syslog_drain_url": "https://syslog.example.org/drain",
"volume_mounts": [],
"provider": null
}
]
}
},
"application_env_json": {
"VCAP_APPLICATION": {
"limits": {
"fds": 16384
},
"application_name": "my_app",
"application_uris": [ "my_app.example.org" ],
"name": "my_app",
"space_name": "my_space",
"space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
"uris": [ "my_app.example.org" ],
"users": null
}
}
}
Retrieve the environment variables that will be provided to an app at runtime. It will include environment variables for Environment Variable Groups and Service Bindings.
Definition
GET /v3/apps/:guid/env
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Space Developer | |
Space Supporter | system_env_json redacted |
Get environment variables for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/environment_variables" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"var": {
"RAILS_ENV": "production"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/[guid]/environment_variables"
},
"app": {
"href": "https://api.example.org/v3/apps/[guid]"
}
}
}
Retrieve the environment variables that are associated with the given app. For the entire list of environment variables that will be available to the app at runtime, see the env endpoint.
Definition
GET /v3/apps/:guid/environment_variables
Permitted roles
Admin |
Admin Read-Only |
Space Developer |
Space Supporter |
Get permissions for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/permissions" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"read_basic_data": true,
"read_sensitive_data": false
}
Get the current user’s permissions for the given app. If a user can see an app, then they can see its basic data. Only admin, read-only admins, and space developers can read sensitive data.
Definition
GET /v3/apps/:guid/permissions
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Set current droplet
Example Request
curl "https://api.example.org/v3/apps/[guid]/relationships/current_droplet" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{ "data": { "guid": "[droplet_guid]" } }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet"
},
"related": {
"href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/droplets/current"
}
}
}
Set the current droplet for an app. The current droplet is the droplet that the app will use when running.
Definition
PATCH /v3/apps/:guid/relationships/current_droplet
Permitted roles
Admin |
Space Developer |
Space Supporter |
Get SSH enabled for an app
Example Request
curl "https://api.example.org/v3/apps/:guid/ssh_enabled" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"enabled": false,
"reason": "Disabled globally"
}
Returns if an application’s runtime environment will accept ssh connections.
If ssh is disabled,
the reason
field will describe
whether it is disabled globally, at the space level, or at the app level.
Definition
GET /v3/apps/:guid/ssh_enabled
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Start an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/actions/start" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STARTED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
},
"features": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
POST /v3/apps/:guid/actions/start
Permitted roles
Admin |
Space Developer |
Space Supporter |
Stop an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/actions/stop" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STOPPED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
},
"features": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
POST /v3/apps/:guid/actions/stop
Permitted roles
Admin |
Space Developer |
Space Supporter |
Restart an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/actions/restart" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STARTED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs4"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"processes": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
},
"packages": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
},
"environment_variables": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
},
"current_droplet": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
},
"droplets": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
},
"tasks": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
},
"start": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
"method": "POST"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
"method": "POST"
},
"revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
},
"deployed_revisions": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
},
"features": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
This endpoint will synchronously stop and start an application. Unlike the start and stop actions, this endpoint will error if the app is not successfully stopped in the runtime.
For restarting applications without downtime, see the deployments resource.
Definition
POST /v3/apps/:guid/actions/restart
Permitted roles
Admin |
Space Developer |
Space Supporter |
Update environment variables for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/environment_variables" \
-X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer [token]" \
-d '{
"var": {
"DEBUG": "false",
"USER": null
}
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"var": {
"RAILS_ENV": "production",
"DEBUG": "false"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/[guid]/environment_variables"
},
"app": {
"href": "https://api.example.org/v3/apps/[guid]"
}
}
}
Update the environment variables associated with the given app.
The variables given in the request will be merged with the existing app environment variables.
Any requested variables with a value of null
will be removed from the app.
Environment variable names may not start with VCAP_. PORT is not a valid environment variable.
Definition
PATCH /v3/apps/:guid/environment_variables
Permitted roles
Admin |
Space Developer |
Space Supporter |
App Features
App features are used to manage whether optional capabilities are enabled for a given application.
The app feature object
Example App Feature object
{
"name": "ssh",
"description": "Enable SSHing into the app.",
"enabled": true
}
Name | Type | Description |
---|---|---|
name | string | Name of the app feature |
description | string | Description of the app feature |
enabled | boolean | Denotes whether or not the app feature is enabled |
Supported app features
Note: SSH must also be enabled globally and on the space.
Name | Description |
---|---|
ssh | Enable SSHing into the app |
revisions | Enable versioning of an application |
Get an app feature
Example Request
curl "https://api.example.org/v3/apps/[guid]/features/[name]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "ssh",
"description": "Enable SSHing into the app.",
"enabled": true
}
Definition
GET /v3/apps/:guid/features/:name
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
List app features
Example Request
curl "https://api.example.org/v3/apps/[guid]/features" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"resources": [
{
"name": "ssh",
"description": "Enable SSHing into the app.",
"enabled": true
},
{
"name": "revisions",
"description": "Enable versioning of an application",
"enabled": false
}
],
"pagination": {
"total_results": 1,
"total_pages": 1,
"first": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
"last": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
"next": null,
"previous": null
}
}
This endpoint retrieves the list of features for the specified app.
Definition
GET /v3/apps/:guid/features
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Update an app feature
Example Request
curl "https://api.example.org/v3/apps/[guid]/features/[name]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{ "enabled": false }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "ssh",
"description": "Enable SSHing into the app.",
"enabled": true
}
Definition
PATCH /v3/apps/:guid/features/:name
Required parameters
Name | Type | Description |
---|---|---|
enabled | boolean | Denotes whether or not the app feature should be enabled |
Permitted roles
Role | Notes |
---|---|
Admin | |
Space Developer | |
Space Supporter | Can only update revisions feature |
App Usage Events
App usage events are a record of changes in the usage of apps and tasks. Examples include starting an application, scaling an application (from, say, one to three instances), and stopping an application.
Usage events are typically used by billing and chargeback applications.
The app usage event object
Example App Usage Event object
{
"guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
"created_at": "2020-05-28T16:41:23Z",
"updated_at": "2020-05-28T16:41:26Z",
"state": {
"current": "STARTED",
"previous": "STOPPED"
},
"app": {
"guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
"name": "name-1982"
},
"process": {
"guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
"type": "type-1983"
},
"space": {
"guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
"name": "name-1664"
},
"organization": {
"guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
},
"buildpack": {
"guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
"name": "label-64"
},
"task": {
"guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
"name": "name-2929"
},
"memory_in_mb_per_instance": {
"current": 512,
"previous": 256
},
"instance_count": {
"current": 10,
"previous": 5
},
"links": {
"self": {
"href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the event |
created_at | timestamp | The time with zone when the event occurred |
updated_at | timestamp | Identical to created_at (events are created, never updated) |
state.current | string or null |
Current state of the app that this event pertains to, if applicable |
state.previous | string or null |
Previous state of the app that this event pertains to, if applicable |
app.guid | string or null |
Unique identifier of the app that this event pertains to, if applicable |
app.name | string or null |
Name of the app that this event pertains to, if applicable |
process.guid | string or null |
Unique identifier of the process that this event pertains to, if applicable |
process.type | string or null |
Type of the process that this event pertains to, if applicable |
space.guid | string or null |
Unique identifier of the space that this event pertains to, if applicable |
space.name | string or null |
Name of the space that this event pertains to, if applicable |
organization.guid | string or null |
Unique identifier of the org that this event pertains to, if applicable |
buildpack.guid | string or null |
Unique identifier of the buildpack that this event pertains to, if applicable |
buildpack.name | string or null |
Name of the buildpack that this event pertains to, if applicable |
task.guid | string or null |
Unique identifier of the task that this event pertains to, if applicable |
task.name | string or null |
Name of the task that this event pertains to, if applicable |
memory_in_mb_per_instance.current | integer or null |
Current memory in MB of the app that this event pertains to, if applicable |
memory_in_mb_per_instance.previous | integer or null |
Previous memory in MB of the app that this event pertains to, if applicable |
instance_count.current | integer or null |
Current instance count of the app that this event pertains to, if applicable |
instance_count.previous | integer or null |
Previous instance count of the app that this event pertains to, if applicable |
links | links object | Links to related resources |
Get an app usage event
Example Request
curl "https://api.example.org/v3/app_usage_events/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
"created_at": "2020-05-28T16:41:23Z",
"updated_at": "2020-05-28T16:41:26Z",
"state": {
"current": "STARTED",
"previous": "STOPPED"
},
"app": {
"guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
"name": "name-1982"
},
"process": {
"guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
"type": "type-1983"
},
"space": {
"guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
"name": "name-1664"
},
"organization": {
"guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
},
"buildpack": {
"guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
"name": "label-64"
},
"task": {
"guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
"name": "name-2929"
},
"memory_in_mb_per_instance": {
"current": 512,
"previous": 256
},
"instance_count": {
"current": 10,
"previous": 5
},
"links": {
"self": {
"href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
}
}
}
Retrieve an app usage event.
Definition
GET /v3/app_usage_events/:guid
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
List app usage events
Example Request
curl "https://api.example.org/v3/app_usage_events" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 2,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/app_usage_events?page=1&per_page=1"
},
"last": {
"href": "https://api.example.org/v3/app_usage_events?page=2&per_page=1"
},
"next": {
"href": "https://api.example.org/v3/app_usage_events?page=2&per_page=1"
},
"previous": null
},
"resources": [
{
"guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
"created_at": "2020-05-28T16:41:23Z",
"updated_at": "2020-05-28T16:41:26Z",
"state": {
"current": "STARTED",
"previous": "STOPPED"
},
"app": {
"guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
"name": "name-1982"
},
"process": {
"guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
"type": "type-1983"
},
"space": {
"guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
"name": "name-1664"
},
"organization": {
"guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
},
"buildpack": {
"guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
"name": "label-64"
},
"task": {
"guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
"name": "name-2929"
},
"memory_in_mb_per_instance": {
"current": 512,
"previous": 256
},
"instance_count": {
"current": 10,
"previous": 5
},
"links": {
"self": {
"href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
}
}
}
]
}
Retrieve all app usage events the user has access to.
Definition
GET /v3/app_usage_events
Query parameters
Name | Type | Description |
---|---|---|
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid value is created_at |
after_guid | string | Filters out events before and including the event with the given guid |
guids | list of strings | Comma-delimited list of usage event guids to filter by |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
Purge and seed app usage events
Example Request
curl "https://api.example.org/v3/app_usage_events/actions/destructively_purge_all_and_reseed" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Destroys all existing events. Populates new usage events, one for each started app. All populated events will have a created_at
value of current time. There is the potential race condition if apps are currently being started, stopped, or scaled. The seeded usage events will have the same guid as the app.
Definition
POST /v3/app_usage_events/actions/destructively_purge_all_and_reseed
Permitted roles
Admin |
Audit Events
Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions.
For more information, see the Cloud Foundry docs.
Audit Event Types
App lifecycle
audit.app.apply_manifest
audit.app.build.create
audit.app.copy-bits
audit.app.create
audit.app.delete-request
audit.app.deployment.cancel
audit.app.deployment.create
audit.app.droplet.create
audit.app.droplet.delete
audit.app.droplet.download
audit.app.droplet.mapped
audit.app.droplet.upload
audit.app.environment.show
audit.app.environment_variables.show
audit.app.map-route
audit.app.package.create
audit.app.package.delete
audit.app.package.download
audit.app.package.upload
audit.app.process.crash
audit.app.process.create
audit.app.process.delete
audit.app.process.ready
audit.app.process.not-ready
audit.app.process.rescheduling
audit.app.process.scale
audit.app.process.terminate_instance
audit.app.process.update
audit.app.restage
audit.app.restart
audit.app.revision.create
audit.app.revision.environment_variables.show
audit.app.ssh-authorized
audit.app.ssh-unauthorized
audit.app.start
audit.app.stop
audit.app.task.cancel
audit.app.task.create
audit.app.unmap-route
audit.app.update
audit.app.upload-bits
Organization lifecycle
audit.organization.create
audit.organization.delete-request
audit.organization.update
Route lifecycle
audit.route.create
audit.route.delete-request
audit.route.share
audit.route.transfer-owner
audit.route.unshare
audit.route.update
Service lifecycle
audit.service.create
audit.service.delete
audit.service.update
Service_binding lifecycle
audit.service_binding.create
audit.service_binding.delete
audit.service_binding.show
audit.service_binding.start_create
audit.service_binding.start_delete
audit.service_binding.update
Service_broker lifecycle
audit.service_broker.create
audit.service_broker.delete
audit.service_broker.update
Service_dashboard_client lifecycle
audit.service_dashboard_client.create
audit.service_dashboard_client.delete
Service_instance lifecycle
audit.service_instance.bind_route
audit.service_instance.create
audit.service_instance.delete
audit.service_instance.purge
audit.service_instance.share
audit.service_instance.show
audit.service_instance.start_create
audit.service_instance.start_delete
audit.service_instance.start_update
audit.service_instance.unbind_route
audit.service_instance.unshare
audit.service_instance.update
Service_key lifecycle
audit.service_key.create
audit.service_key.delete
audit.service_key.show
audit.service_key.start_create
audit.service_key.start_delete
audit.service_key.update
Service_plan lifecycle
audit.service_plan.create
audit.service_plan.delete
audit.service_plan.update
Service_plan_visibility lifecycle
audit.service_plan_visibility.create
audit.service_plan_visibility.delete
audit.service_plan_visibility.update
Service_route_binding lifecycle
audit.service_route_binding.create
audit.service_route_binding.delete
audit.service_route_binding.start_create
audit.service_route_binding.start_delete
audit.service_route_binding.update
Space lifecycle
audit.space.create
audit.space.delete-request
audit.space.update
User lifecycle
audit.user.organization_auditor_add
audit.user.organization_auditor_remove
audit.user.organization_billing_manager_add
audit.user.organization_billing_manager_remove
audit.user.organization_manager_add
audit.user.organization_manager_remove
audit.user.organization_user_add
audit.user.organization_user_remove
audit.user.space_auditor_add
audit.user.space_auditor_remove
audit.user.space_developer_add
audit.user.space_developer_remove
audit.user.space_manager_add
audit.user.space_manager_remove
audit.user.space_supporter_add
audit.user.space_supporter_remove
User_provided_service_instance lifecycle
audit.user_provided_service_instance.create
audit.user_provided_service_instance.delete
audit.user_provided_service_instance.show
audit.user_provided_service_instance.update
Special events
app.crash
blob.remove_orphan
The audit event object
Example Audit Event object
{
"guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
"created_at": "2016-06-08T16:41:23Z",
"updated_at": "2016-06-08T16:41:26Z",
"type": "audit.app.update",
"actor": {
"guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
"type": "user",
"name": "admin"
},
"target": {
"guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
"type": "app",
"name": "my-app"
},
"data": {
"request": {
"recursive": true
}
},
"space": {
"guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
},
"organization": {
"guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
},
"links": {
"self": {
"href": "https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the event |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
type | string | The type of the event |
actor.guid | string | Unique identifier for the actor (user or system resource that performed the action) |
actor.type | string | The actor type |
actor.name | string | The name of the actor |
target.guid | uuid | Unique identifier for the target (resource that the event acted upon) |
target.type | string | The target type |
target.name | string | The name of the target |
data | object | Additional information about event |
space.guid | uuid | Unique identifier for the space where the event occurred; if the event did not occur within a space, the space field will be null |
organization.guid | uuid | Unique identifier for the organization where the event occurred; if the event did not occur within an organization, the organization field will be null |
links | links object | Links to related resources |
Get an audit event
Example Request
curl "https://api.example.org/v3/audit_events/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
"created_at": "2016-06-08T16:41:23Z",
"updated_at": "2016-06-08T16:41:26Z",
"type": "audit.app.update",
"actor": {
"guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
"type": "user",
"name": "admin"
},
"target": {
"guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
"type": "app",
"name": "my-app"
},
"data": {
"request": {
"recursive": true
}
},
"space": {
"guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
},
"organization": {
"guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
},
"links": {
"self": {
"href": "https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
}
}
}
Definition
GET /v3/audit_events/:guid
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Global Auditor | |
Org Auditor | Cannot see events which occurred in orgs that the user does not belong to |
Space Auditor | Cannot see events which occurred in spaces that the user does not belong to |
Space Developer | Cannot see events which occurred in spaces that the user does not belong to |
Space Supporter | Cannot see events which occurred in spaces that the user does not belong to |
List audit events
Example Request
curl "https://api.example.org/v3/audit_events" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 1,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/audit_events?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/audit_events?page=1&per_page=2"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
"created_at": "2016-06-08T16:41:23Z",
"updated_at": "2016-06-08T16:41:26Z",
"type": "audit.app.update",
"actor": {
"guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
"type": "user",
"name": "admin"
},
"target": {
"guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
"type": "app",
"name": "my-app"
},
"data": {
"request": {
"recursive": true
}
},
"space": {
"guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
},
"organization": {
"guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
},
"links": {
"self": {
"href": "https://api.example.org//v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
}
}
}
]
}
Retrieve all audit events the user has access to.
Definition
GET /v3/audit_events
Query parameters
Name | Type | Description |
---|---|---|
types | list of strings | Comma-delimited list of event types to filter by |
target_guids | list of strings | Comma-delimited list of target guids to filter by. Also supports filtering by exclusion. |
space_guids | list of strings | Comma-delimited list of space guids to filter by |
organization_guids | list of strings | Comma-delimited list of organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at , updated_at |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Builds
Builds represent the process of staging an application package. There are two types (lifecycles) of builds: buildpack and docker.
After an application is created and packages are uploaded, a build resource can be created to initiate the staging process. A successful build results in a droplet.
The build object
Example Build object
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"created_by": {
"guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
"name": "bill",
"email": "[email protected]"
},
"state": "STAGED",
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 1024,
"staging_log_rate_limit_bytes_per_second": 1024,
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs4"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": {
"guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
},
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the build |
created_at | timestamp | The time with zone when the build was created |
updated_at | timestamp | The time with zone when the build was last updated |
state | string | State of the build; valid states are STAGING , STAGED , or FAILED |
staging_memory_in_mb | integer | Memory in MB allocated for staging of the build |
staging_disk_in_mb | integer | Disk space in MB allocated for staging of the build |
staging_log_rate_limit_bytes_per_second | integer | Log rate limit in bytes per second allocated for staging of the build |
error | string | A string describing errors during the build process |
lifecycle | lifecycle object | Provides the lifecycle object to use during staging; this will override the build’s application’s default lifecycle for this build |
package.guid | string | The package that is the input to the staging process |
droplet.guid | string | A resulting droplet from the staging process; droplet will be null if staging has not completed |
created_by.guid | object | The guid of the user that created the build |
created_by.name | object | The name of the user that created the build |
created_by.email | object | The email of the user that created the build |
relationships.app | to-one relationship | The app the build belongs to |
metadata.labels | label object | Labels applied to the build |
metadata.annotations | annotation object | Annotations applied to the build |
links | links object | Links to related resources |
Create a build
Example Request
curl "https://api.example.org/v3/builds" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"package": {
"guid": "[package-guid]"
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-06-08T16:41:26Z",
"created_by": {
"guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
"name": "bill",
"email": "[email protected]"
},
"state": "STAGING",
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 1024,
"staging_log_rate_limit_bytes_per_second": 1024,
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs4"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": null,
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
}
Definition
POST /v3/builds
Required parameters
Name | Type | Description |
---|---|---|
package | object | App package to stage |
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
lifecycle | lifecycle object | Lifecycle information for a build | lifecycle on the app |
staging_memory_in_mb | integer | Memory in MB allocated for staging of the build | |
staging_disk_in_mb | integer | Disk space in MB allocated for staging of the build | |
staging_log_rate_limit_bytes_per_second | integer | Log rate limit in bytes per second allocated for staging of the build | |
metadata.labels | label object | Labels applied to the build | |
metadata.annotations | annotation object | Annotations applied to the build |
Permitted roles
Admin |
Space Developer |
Space Supporter |
Get a build
Example Request
curl "https://api.example.org/v3/builds/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"created_by": {
"guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
"name": "bill",
"email": "[email protected]"
},
"state": "STAGED",
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 1024,
"staging_log_rate_limit_bytes_per_second": 1024,
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs4"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": {
"guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
},
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
}
}
}
Definition
GET /v3/builds/:guid
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
List builds
Example Request
curl "https://api.example.org/v3/builds" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 1,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-06-08T16:41:26Z",
"created_by": {
"guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
"name": "bill",
"email": "[email protected]"
},
"state": "STAGING",
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 1024,
"staging_log_rate_limit_bytes_per_second": 1024,
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs4"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": null,
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
}
]
}
Retrieve all builds the user has access to.
Definition
GET /v3/builds
Query parameters
Name | Type | Description |
---|---|---|
states | list of strings | Comma-delimited list of build states to filter by |
app_guids | list of strings | Comma-delimited list of app guids to filter by |
package_guids | list of strings | Comma-delimited list of package guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
List builds for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/builds" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 1,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/apps/[guid]/builds?states=STAGING&page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/apps/[guid]/builds?states=STAGING&page=1&per_page=2"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-06-08T16:41:26Z",
"created_by": {
"guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
"name": "bill",
"email": "[email protected]"
},
"state": "STAGING",
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 1024,
"staging_log_rate_limit_bytes_per_second": 1024,
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs4"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": null,
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
}
]
}
Retrieve all builds for the app.
Definition
GET /v3/apps/:guid/builds
Query parameters
Name | Type | Description |
---|---|---|
states | list of strings | Comma-delimited list of build states to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Update a build
Example Request
curl "https://api.example.org/v3/builds/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"created_by": {
"guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
"name": "bill",
"email": "[email protected]"
},
"state": "STAGED",
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 1024,
"staging_log_rate_limit_bytes_per_second": 1024,
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs4"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": {
"guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
},
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"metadata": {
"labels": {"key":"value"},
"annotations": {"note":"detailed information"}
},
"links": {
"self": {
"href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
}
}
}
Definition
PATCH /v3/builds/:guid
Optional parameters
Name | Type | Description |
---|---|---|
metadata.labels | label object | Labels applied to the build |
metadata.annotations | annotation object | Annotations applied to the build |
state | string | Build status; valid values are FAILED or STAGED (field can only be passed by Build State Updaters) |
lifecycle.data.image | string | Image reference tag where the built complete image was stored (field can only be passed by Build State Updaters) |
Permitted roles
Role | Notes |
---|---|
Admin | |
Space Developer | |
Build State Updater | This is a special component role; read more about component roles |
Buildpacks
Buildpacks are used during a build to download external dependencies and transform a package into an executable droplet. In this way, buildpacks are a pluggable extension to Cloud Foundry that enable CF to run different languages and frameworks. Buildpacks will automatically detect if they support an application. Buildpacks can also be explicitly specified on apps and builds.
The buildpack object
Example Buildpack object
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "ruby_buildpack",
"state": "AWAITING_UPLOAD",
"filename": null,
"stack": "windows64",
"position": 42,
"enabled": true,
"locked": false,
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
},
"upload": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
"method": "POST"
}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the buildpack |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
name | string | The name of the buildpack; to be used by app buildpack field (only alphanumeric characters) |
state | string | The state of the buildpack; valid states are: AWAITING_UPLOAD , READY |
stack | string | The name of the stack that the buildpack will use |
filename | string | The filename of the buildpack |
position | integer | The order in which the buildpacks are checked during buildpack auto-detection |
enabled | boolean | Whether or not the buildpack can be used for staging |
locked | boolean | Whether or not the buildpack is locked to prevent updating the bits |
metadata.labels | label object | Labels applied to the app |
metadata.annotations | annotation object | Annotations added to the app |
links | links object | Links to related resources |
Create a buildpack
Example Request
curl "https://api.example.org/v3/buildpacks" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "ruby_buildpack",
"position": 42,
"enabled": true,
"locked": false,
"stack": "windows64"
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "ruby_buildpack",
"state": "AWAITING_UPLOAD",
"filename": null,
"stack": "windows64",
"position": 42,
"enabled": true,
"locked": false,
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
},
"upload": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
"method": "POST"
}
}
}
Definition
POST /v3/buildpacks
Required parameters
Name | Type | Description |
---|---|---|
name | string | Name of the buildpack |
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
stack | string | The name of the stack that the buildpack will use | null |
position | integer | The order in which the buildpacks are checked during buildpack auto-detection | 1 |
enabled | boolean | Whether or not the buildpack will be used for staging | true |
locked | boolean | Whether or not the buildpack is locked to prevent updating the bits | false |
metadata.labels | label object | Labels applied to the buildpack | |
metadata.annotations | annotation object | Annotations applied to the buildpack |
Permitted roles
Admin |
Get a buildpack
Example Request
curl "https://api.example.org/v3/buildpacks/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "ruby_buildpack",
"state": "AWAITING_UPLOAD",
"filename": null,
"stack": "windows64",
"position": 42,
"enabled": true,
"locked": false,
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
},
"upload": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
"method": "POST"
}
}
}
Definition
GET /v3/buildpacks/:guid
Permitted roles
All Roles |
List buildpacks
Example Request
curl "https://api.example.org/v3/buildpacks" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 3,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/buildpacks?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/buildpacks?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/buildpacks?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "my-buildpack",
"state": "AWAITING_UPLOAD",
"filename": null,
"stack": "my-stack",
"position": 1,
"enabled": true,
"locked": false,
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
},
"upload": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
"method": "POST"
}
}
}
]
}
Retrieve all buildpacks the user has access to.
Definition
GET /v3/buildpacks
Query parameters
Name | Type | Description |
---|---|---|
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
names | list of strings | Comma-delimited list of buildpack names to filter by |
stacks | list of strings | Comma-delimited list of stack names to filter by |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at , and position |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
Update a buildpack
Example Request
curl "https://api.example.org/v3/buildpacks/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "ruby_buildpack",
"position": 42,
"enabled": true,
"locked": false,
"stack": "windows64"
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "ruby_buildpack",
"state": "AWAITING_UPLOAD",
"filename": null,
"stack": "windows64",
"position": 42,
"enabled": true,
"locked": false,
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
},
"upload": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
"method": "POST"
}
}
}
Definition
PATCH /v3/buildpacks/:guid
Optional parameters
Name | Type | Description |
---|---|---|
name | string | Name of the buildpack |
stack | string | The name of the stack that the buildpack will use |
position | integer | The order in which the buildpacks are checked during buildpack auto-detection |
enabled | boolean | Whether or not the buildpack will be used for staging |
locked | boolean | Whether or not the buildpack is locked to prevent updating the bits |
metadata.labels | label object | Labels applied to the buildpack |
metadata.annotations | annotation object | Annotations applied to the buildpack |
Permitted roles
Admin |
Delete a buildpack
Example Request
curl "https://api.example.org/v3/buildpacks/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Definition
DELETE /v3/buildpacks/:guid
Permitted roles
Admin |
Upload buildpack bits
Example Request
curl "https://api.example.org/v3/buildpacks/[guid]/upload" \
-X POST \
-H "Authorization: bearer [token]" \
-F bits=@"buildpack.zip"
Example Response
HTTP/1.1 202 OK
Content-Type: application/json
Location: https://api.example.org/v3/jobs/[guid]
{
"guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
"created_at": "2016-03-18T23:26:46Z",
"updated_at": "2016-10-17T20:00:42Z",
"name": "ruby_buildpack",
"state": "AWAITING_UPLOAD",
"filename": null,
"stack": "windows64",
"position": 42,
"enabled": true,
"locked": false,
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
},
"upload": {
"href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
"method": "POST"
}
}
}
Upload a zip file containing a Cloud Foundry compatible buildpack. The file must be sent as part of a multi-part form.
Definition
POST /v3/buildpacks/:guid/upload
Required parameters
Name | Type | Description |
---|---|---|
bits | form field | A binary zip file containing the buildpack bits |
Permitted roles
Admin |
Deployments
Deployments are objects that manage updates to applications with zero downtime.
They can either:
Manage updating an app’s droplet directly after an application package is staged
Roll an app back to a specific revision along with its associated droplet
It is possible to use rolling deployments for applications without incurring downtime. This is different from the traditional method of pushing app updates which performs start/stop deployments.
The deployment object
Example Deployment object
{
"guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
"status": {
"value": "ACTIVE",
"reason": "DEPLOYING",
"details": {
"last_successful_healthcheck": "2018-04-25T22:42:10Z"
}
},
"strategy": "rolling",
"droplet": {
"guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
},
"previous_droplet": {
"guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
},
"new_processes": [
{
"guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
"type": "web"
}
],
"revision": {
"guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
"version": 1
},
"created_at": "2018-04-25T22:42:10Z",
"updated_at": "2018-04-25T22:42:10Z",
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"app": {
"data": {
"guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
},
"app": {
"href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
},
"cancel": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
"method": "POST"
}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the deployment |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
status.value | string | The current status of the deployment; valid values are ACTIVE (meaning in progress) and FINALIZED (meaning finished, either successfully or not) |
status.reason | string | The reason for the status of the deployment; following list represents valid values: 1. If status.value is ACTIVE - DEPLOYING - CANCELING 2. If status.value is FINALIZED - DEPLOYED - CANCELED - SUPERSEDED (another deployment created for app before completion) |
status.details | object | The details for the status of the deployment shows a timestamp of the last successful healthcheck |
strategy | string | Strategy used for the deployment; supported strategies are rolling only |
droplet.guid | string | The droplet guid that the deployment is transitioning the app to |
previous_droplet.guid | string | The app’s current droplet guid before the deployment was created |
new_processes | array | List of processes created as part of the deployment |
revision | object | The revision the deployment is transitioning the app to |
relationships.app | to-one relationship | The app the deployment is updating |
metadata.labels | label object | Labels applied to the deployment |
metadata.annotations | annotation object | Annotations applied to the deployment |
links | links object | Links to related resources |
Create a deployment
Example Request with Droplet
curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"droplet": {
"guid": "[droplet-guid]"
},
"strategy": "rolling",
"relationships": {
"app": {
"data": {
"guid": "[app-guid]"
}
}
}
}'
Example Request with Revision
curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"revision": {
"guid": "[revision-guid]"
},
"strategy": "rolling",
"relationships": {
"app": {
"data": {
"guid": "[app-guid]"
}
}
}
}'
Example Response
HTTP/1.1 201 OK
Content-Type: application/json
{
"guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
"status": {
"value": "ACTIVE",
"reason": "DEPLOYING",
"details": {
"last_successful_healthcheck": "2018-04-25T22:42:10Z"
}
},
"strategy": "rolling",
"droplet": {
"guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
},
"previous_droplet": {
"guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
},
"new_processes": [
{
"guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
"type": "web"
}
],
"revision": {
"guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
"version": 1
},
"created_at": "2018-04-25T22:42:10Z",
"updated_at": "2018-04-25T22:42:10Z",
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"app": {
"data": {
"guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
},
"app": {
"href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
},
"cancel": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
"method": "POST"
}
}
}
When you create a new deployment you can either provide a specific droplet or revision to deploy. If no revision or droplet is provided, the droplet associated with the app is deployed.
Definition
POST /v3/deployments
Required parameters
Name | Type | Description |
---|---|---|
relationships.app | to-one relationship | The app to deploy a droplet for |
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
droplet[1] | object | The droplet to deploy for the app; this will update the app’s current droplet to this droplet | The app’s current droplet |
revision[1] | object | The revision whose droplet to deploy for the app; this will update the app’s current droplet to this droplet | |
strategy | string | The strategy to use for the deployment | rolling |
metadata.labels | label object | Labels applied to the deployment | |
metadata.annotations | annotation object | Annotations applied to the deployment |
1 Only a droplet or a revision may be provided, not both.
Permitted roles
Admin |
Space Developer |
Space Supporter |
Get a deployment
Example Request
curl "https://api.example.org/v3/deployments/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
"status": {
"value": "ACTIVE",
"reason": "DEPLOYING",
"details": {
"last_successful_healthcheck": "2018-04-25T22:42:10Z"
}
},
"strategy": "rolling",
"droplet": {
"guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
},
"previous_droplet": {
"guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
},
"new_processes": [
{
"guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
"type": "web"
}
],
"revision": {
"guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
"version": 1
},
"created_at": "2018-04-25T22:42:10Z",
"updated_at": "2018-04-25T22:42:10Z",
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"app": {
"data": {
"guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
},
"app": {
"href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
},
"cancel": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
"method": "POST"
}
}
}
Definition
GET /v3/deployments/:guid
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
List deployments
Example Request
curl "https://api.example.org/v3/deployments" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 1,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/deployments?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/deployments?page=1&per_page=2"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
"status": {
"value": "FINALIZED",
"reason": "DEPLOYED"
},
"strategy": "rolling",
"droplet": {
"guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
},
"previous_droplet": {
"guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
},
"new_processes": [
{
"guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
"type": "web-deployment-59c3d133-2b83-46f3-960e-7765a129aea4"
}
],
"revision": {
"guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
"version": 1
},
"created_at": "2018-04-25T22:42:10Z",
"updated_at": "2018-04-25T22:42:10Z",
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"app": {
"data": {
"guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
},
"app": {
"href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
}
}
}
]
}
Retrieve all deployments the user has access to.
Definition
GET /v3/deployments
Query parameters
Name | Type | Description |
---|---|---|
app_guids | list of strings | Comma-delimited list of app guids to filter by |
states | list of strings | Comma-delimited list of states to filter by |
status_reasons | list of strings | Comma-delimited list of status reasons to filter by; valid values include DEPLOYING , CANCELING , DEPLOYED , CANCELED , SUPERSEDED |
status_values | list of strings | Comma-delimited list of status values to filter by; valid values include ACTIVE and FINALIZED |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at , updated_at |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
Update a deployment
Example Request
curl "https://api.example.org/v3/deployments/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
"status": {
"value": "ACTIVE",
"reason": "DEPLOYING",
"details": {
"last_successful_healthcheck": "2018-04-25T22:42:10Z"
}
},
"strategy": "rolling",
"droplet": {
"guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
},
"previous_droplet": {
"guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
},
"new_processes": [
{
"guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
"type": "web"
}
],
"revision": {
"guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
"version": 1
},
"created_at": "2018-04-25T22:42:10Z",
"updated_at": "2018-04-25T22:42:10Z",
"metadata": {
"labels": {"key":"value"},
"annotations": {"note":"detailed information"}
},
"relationships": {
"app": {
"data": {
"guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
},
"app": {
"href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
},
"cancel": {
"href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
"method": "POST"
}
}
}
Definition
PATCH /v3/deployments/:guid
Optional parameters
Name | Type | Description |
---|---|---|
metadata.labels | label object | Labels applied to the deployment |
metadata.annotations | annotation object | Annotations applied to the deployment |
Permitted roles
Admin |
Space Developer |
Cancel a deployment
Example Request
curl "https://api.example.org/v3/deployments/[guid]/actions/cancel" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Definition
POST /v3/deployments/:guid/actions/cancel
Permitted roles
Admin |
Space Developer |
Space Supporter |
Domains
Domains represent a fully qualified domain name that is used for application routes.
A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.
The domain object
Example Domain object
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"name": "test-domain.com",
"internal": false,
"router_group": null,
"supported_protocols": ["http"],
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"organization": {
"data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
},
"shared_organizations": {
"data": [
{"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
{"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
]
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
},
"organization": {
"href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
},
"route_reservations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
},
"shared_organizations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the domain |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
name | string | The name of the domain; must be between 3 ~ 253 characters and follow RFC 1035 |
internal | boolean | Whether the domain is used for internal (container-to-container) traffic |
router_group.guid | uuid | The guid of the desired router group to route tcp traffic through; if set, the domain will only be available for tcp traffic |
supported_protocols | list of strings | Available protocols for routes using the domain, currently http and tcp |
relationships.organization | to-one relationship | The organization the domain is scoped to; if set, the domain will only be available in that organization; otherwise, the domain will be globally available |
relationships.shared_organizations | to-many relationship | Organizations the domain is shared with; if set, the domain will be available in these organizations in addition to the organization the domain is scoped to |
metadata.labels | label object | Labels applied to the domain |
metadata.annotations | annotation object | Annotations applied to the domain |
links | links object | Links to related resources |
Create a domain
Example Request
curl "https://api.example.org/v3/domains" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "example.com",
"internal": false
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"name": "test-domain.com",
"internal": false,
"router_group": null,
"supported_protocols": ["http"],
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"organization": {
"data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
},
"shared_organizations": {
"data": [
{"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
{"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
]
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
},
"organization": {
"href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
},
"route_reservations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
},
"shared_organizations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
}
}
}
Definition
POST /v3/domains
Required parameters
Name | Type | Description |
---|---|---|
name | string | Name of the domain |
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
internal | boolean | Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic | false |
router_group.guid | uuid | The desired router group guid. note: creates a tcp domain; cannot be used when internal is set to true or domain is scoped to an org |
null |
organization | to-one relationship | A relationship to the organization the domain will be scoped to; note: cannot be used when internal is set to true or domain is associated with a router group |
|
shared_organizations | to-many relationship | A relationship to organizations the domain will be shared with Note: cannot be used without an organization relationship |
|
metadata.labels | label object | Labels applied to the domain | |
metadata.annotations | annotation object | Annotations applied to the domain |
Permitted roles
Role | Notes |
---|---|
Admin | |
Org Manager | When an organization relationship is provided |
Get a domain
Example Request
curl "https://api.example.org/v3/domains/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"name": "test-domain.com",
"internal": false,
"router_group": null,
"supported_protocols": ["http"],
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"organization": {
"data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
},
"shared_organizations": {
"data": [
{"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
{"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
]
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
},
"organization": {
"href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
},
"route_reservations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
},
"shared_organizations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
}
}
}
Definition
GET /v3/domains/:guid
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Global Auditor | |
Org Auditor | |
Org Billing Manager | Can only view domains without an organization relationship |
Org Manager | |
Space Auditor | |
Space Developer | |
Space Manager | |
Space Supporter |
List domains
Example Request
curl "https://api.example.org/v3/domains" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 3,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/domains?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/domains?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/domains?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"name": "test-domain.com",
"internal": false,
"router_group": { "guid": "5806148f-cce6-4d86-7fbd-aa269e3f6f3f" },
"supported_protocols": ["tcp"],
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"organization": {
"data": null
},
"shared_organizations": {
"data": []
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
},
"route_reservations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
},
"router_group": {
"href": "https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f"
}
}
},
]
}
Retrieve all domains the user has access to.
Definition
GET /v3/domains
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of guids to filter by |
names | list of strings | Comma-delimited list of domain names to filter by |
organization_guids | list of strings | Comma-delimited list of owning organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at , updated_at |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
List domains for an organization
Example Request
curl "https://api.example.org/v3/organizations/[guid]/domains" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 3,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/organizations/[guid]/domains?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/organizations/[guid]/domains?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/organizations/[guid]/domains?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"name": "test-domain.com",
"internal": false,
"router_group": { "guid": "5806148f-cce6-4d86-7fbd-aa269e3f6f3f" },
"supported_protocols": ["tcp"],
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"organization": {
"data": null
},
"shared_organizations": {
"data": []
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
},
"route_reservations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
},
"router_group": {
"href": "https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f"
}
}
},
]
}
Retrieve all domains available in an organization for the current user. This will return unscoped domains (those without an owning organization), domains that are scoped to the given organization (owned by the given organization), and domains that have been shared with the organization.
To retrieve the default domain for an organization, use the get default domain endpoint.
Definition
GET /v3/organizations/:guid/domains
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of guids to filter by |
names | list of strings | Comma-delimited list of domain names to filter by |
organization_guids | list of strings | Comma-delimited list of owning organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at , updated_at |
label_selector | string | A query string containing a list of label selector requirements |
Permitted roles
All Roles |
Update a domain
Example Request
curl "https://api.example.org/v3/domains/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"metadata": {
"labels": {"key": "value"},
"annotations": {"note": "detailed information"}
}
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"name": "test-domain.com",
"internal": false,
"router_group": null,
"supported_protocols": ["http"],
"metadata": {
"labels": {"key":"value"},
"annotations": {"note":"detailed information"}
},
"relationships": {
"organization": {
"data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
},
"shared_organizations": {
"data": [
{"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
{"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
]
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
},
"organization": {
"href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
},
"route_reservations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
},
"shared_organizations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
}
}
}
Definition
PATCH /v3/domains/:guid
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
metadata.labels | label object | Labels applied to the domain | |
metadata.annotations | annotation object | Annotations applied to the domain |
Permitted roles
Role | Notes |
---|---|
Admin | |
Org Manager | If domain is scoped to organization managed by the org manager |
Delete a domain
Example Request
curl "https://api.example.org/v3/domains/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Definition
DELETE /v3/domains/:guid
Permitted roles
Role | Notes |
---|---|
Admin | |
Org Manager | If domain is scoped to organization managed by the org manager |
Share a domain
Example Request
curl "https://api.example.org/v3/domains/[guid]/relationships/shared_organizations" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"data": [
{"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
{"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
]
}'
Example Response
HTTP/1.1 200 Created
Content-Type: application/json
{
"data": [
{"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"}
{"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
]
}
This endpoint shares an organization-scoped domain to other organizations specified by a list of organization guids. This will allow any of the other organizations to use the organization-scoped domain.
Definition
POST /v3/domains/:guid/relationships/shared_organizations
Required parameters
Name | Type | Description |
---|---|---|
data | to-many relationship | The organization guids with which to share the domain |
Permitted roles
Admin |
Org Manager |
Unshare a domain
Example Request
curl "https://api.example.org/v3/domains/[guid]/relationships/shared_organizations/[org_guid]" \
-X DELETE \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json"
Example Response
HTTP/1.1 204 No Content
This endpoint removes an organization from the list of organizations an organization-scoped domain is shared with. This prevents the organization from using the organization-scoped domain.
Definition
DELETE /v3/domains/:guid/relationships/shared_organizations/:org_guid
Permitted roles
Role | Notes |
---|---|
Admin | |
Org Manager | Can be in either the domain’s owning organization or the organization it has been shared to |
Droplets
Droplets are the result of staging an application package. There are two types (lifecycles) of droplets: buildpack and docker. In the case of the buildpacks, the droplet contains the bits produced by the buildpack, typically application code and dependencies.
After an application is created and packages are uploaded, a droplet must be created via a build in order for an application to be deployed or tasks to be run. The current droplet must be assigned to an application before it may be started. When tasks are created, they either use a specific droplet guid, or use the current droplet assigned to an application.
The droplet object
Example Droplet object
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"checksum": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpacks": [
{
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14",
"version": "1.1.1.",
"buildpack_name": "ruby"
}
],
"stack": "cflinuxfs4",
"image": null,
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"package": {
"href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
},
"download": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the droplet |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
state | string | State of the droplet; valid states are AWAITING_UPLOAD , PROCESSING_UPLOAD , STAGED , COPYING , FAILED , or EXPIRED |
error | string | A string describing the last error during the droplet lifecycle |
lifecycle | lifecycle object | An object describing the lifecycle that was used when staging the droplet; lifecycle.data will always be an empty hash for lifecycles of type docker |
execution_metadata | string | Serialized JSON data resulting from staging for use when executing a droplet |
process_types | object | The process types (keys) and associated start commands (values) that will be created when the droplet is executed |
relationships.app | to-one relationship | The app the droplet belongs to |
metadata.labels | labels object | Labels on the droplet |
metadata.annotations | annotations object | Annotations on the droplet |
links | links object | Links to related resources |
In addition to these fields, a droplet object will contain the following fields from both lifecycles.
Their values will be null
by default and will contain values when the droplet is of a specific lifecycle.type.
Buildpack droplet
Name | Type | Description |
---|---|---|
checksum.type | string | Hashing algorithm for checksum; supported algorithms are sha256 and sha1 |
checksum.value | string | Checksum of droplet |
buildpacks | array of detected buildpack objects | Detected buildpacks from the staging process |
stack | string | The root filesystem to use with the buildpack, for example cflinuxfs4 |
Detected buildpack object
Name | Type | Description |
---|---|---|
name | string | System buildpack name |
detect_output | string | Output during buildpack detect process |
buildpack_name | string | Name reported by the buildpack |
version | string | Version reported by the buildpack |
Docker droplet
Name | Type | Description |
---|---|---|
image | string | Docker image name |
Create a droplet
Example Request
curl "https://api.example.org/v3/droplets" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"relationships": {
"app": {
"data": {
"guid": "[app-guid]"
}
}
},
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "AWAITING_UPLOAD",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"checksum": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpacks": [
{
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14",
"version": "1.1.1.",
"buildpack_name": "ruby"
}
],
"stack": "cflinuxfs4",
"image": null,
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
},
"upload": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/upload",
"method": "POST"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
This endpoint is only for creating a droplet without a package. To create a droplet based on a package, see Create a build.
Definition
POST /v3/droplets
Required parameters
Name | Type | Description |
---|---|---|
app | to-one relationship | App to create droplet for |
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
process_types | hash | Process names and start commands for the droplet | {"web": ""} |
Permitted roles
Admin | |
Space Developer |
Get a droplet
Example Request
curl "https://api.example.org/v3/droplets/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"checksum": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpacks": [
{
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14",
"version": "1.1.1.",
"buildpack_name": "ruby"
}
],
"stack": "cflinuxfs4",
"image": null,
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"package": {
"href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
},
"download": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
GET /v3/droplets/:guid
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Global Auditor | Some fields are redacted |
Org Manager | Some fields are redacted |
Space Auditor | Some fields are redacted |
Space Developer | |
Space Manager | Some fields are redacted |
Space Supporter | Some fields are redacted |
List droplets
Example Request
curl "https://api.example.org/v3/droplets" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 2,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/droplets?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/droplets?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"image": null,
"execution_metadata": "PRIVATE DATA HIDDEN",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"checksum": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpacks": [
{
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14",
"version": "1.1.1.",
"buildpack_name": "ruby"
}
],
"stack": "cflinuxfs4",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"package": {
"href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
},
"download": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "docker",
"data": {}
},
"execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"image": "cloudfoundry/diego-docker-app-custom:latest",
"checksum": null,
"buildpacks": null,
"stack": null,
"created_at": "2016-03-17T00:00:01Z",
"updated_at": "2016-03-17T21:41:32Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
},
"package": {
"href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve all droplets the user has access to.
Definition
GET /v3/droplets
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of droplet guids to filter by |
states | list of strings | Comma-delimited list of droplet states to filter by |
app_guids | list of strings | Comma-delimited list of app guids to filter by |
space_guids | list of strings | Comma-delimited list of space guids to filter by |
organization_guids | list of strings | Comma-delimited list of organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at and updated_at |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
List droplets for a package
Example Request
curl "https://api.example.org/v3/packages/[guid]/droplets" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 2,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"image": null,
"execution_metadata": "PRIVATE DATA HIDDEN",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"checksum": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpacks": [
{
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14",
"version": "1.1.1.",
"buildpack_name": "ruby"
}
],
"stack": "cflinuxfs4",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"package": {
"href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
},
"download": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "docker",
"data": {}
},
"execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"image": "cloudfoundry/diego-docker-app-custom:latest",
"checksum": null,
"buildpacks": null,
"stack": null,
"created_at": "2016-03-17T00:00:01Z",
"updated_at": "2016-03-17T21:41:32Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
},
"package": {
"href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve a list of droplets belonging to a package.
Definition
GET /v3/packages/:guid/droplets
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of droplet guids to filter by |
states | list of strings | Comma-delimited list of droplet states to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at and updated_at |
label_selector | string | A query string containing a list of label selector requirements |
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
List droplets for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/droplets" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 2,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"image": null,
"execution_metadata": "PRIVATE DATA HIDDEN",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"checksum": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpacks": [
{
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14",
"version": "1.1.1.",
"buildpack_name": "ruby"
}
],
"stack": "cflinuxfs4",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"package": {
"href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
},
"download": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "docker",
"data": {}
},
"execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"image": "cloudfoundry/diego-docker-app-custom:latest",
"checksum": null,
"buildpacks": null,
"stack": null,
"created_at": "2016-03-17T00:00:01Z",
"updated_at": "2016-03-17T21:41:32Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
},
"package": {
"href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve a list of droplets belonging to an app.
Definition
GET /v3/apps/:guid/droplets
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of droplet guids to filter by |
states | list of strings | Comma-delimited list of droplet states to filter by |
current | boolean | If true, only include the droplet currently assigned to the app |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at and updated_at |
label_selector | string | A query string containing a list of label selector requirements |
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Update a droplet
Example Request
curl "https://api.example.space/v3/droplets/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"checksum": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpacks": [
{
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14",
"version": "1.1.1.",
"buildpack_name": "ruby"
}
],
"stack": "cflinuxfs4",
"image": null,
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"package": {
"href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
},
"download": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
}
},
"metadata": {
"labels": {
"release": "stable"
},
"annotations": {
"note": "detailed information"
}
}
}
Definition
PATCH /v3/droplets/:guid
Optional parameters
Name | Type | Description |
---|---|---|
metadata.labels | label object | Labels applied to the droplet |
metadata.annotations | annotation object | Annotations applied to the droplet |
image | string | Image reference where the built complete image was stored (field can only be passed by Build State Updaters) |
Permitted roles
Role | Notes |
---|---|
Admin | |
Space Developer | |
Build State Updater | This is a special component role; read more about component roles |
Delete a droplet
Example Request
curl "https://api.example.org/v3/droplets/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Definition
DELETE /v3/droplets/:guid
Permitted roles
Admin |
Space Developer |
Copy a droplet
Example Request
curl "https://api.example.org/v3/droplets?source_guid=[guid]" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"relationships": {
"app": {
"data": {
"guid": "[app-guid]"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "COPYING",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"execution_metadata": "",
"process_types": null,
"checksum": null,
"buildpacks": null,
"stack": null,
"image": null,
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"package": {
"href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
"method": "PATCH"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Copy a droplet to a different app. The copied droplet excludes the environment variables listed on the source droplet.
Definition
POST /v3/droplets?source_guid=:guid
Required query parameters
Name | Type | Description |
---|---|---|
source_guid | uuid | Source guid of the droplet to be copied |
Required parameters
Name | Type | Description |
---|---|---|
relationships.app | to-one relationship | A relationship to the destination app |
Permitted roles
Admin |
Space Developer |
Download droplet bits
Example Request
curl "https://api.example.org/v3/droplets/[guid]/download" \
-X GET \
-H "Authorization: bearer [token]" \
Example Response
HTTP/1.1 302 FOUND
Content-Type: application/json
Download a gzip compressed tarball file containing a Cloud Foundry compatible droplet. When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits. If the client is automatically following redirects, then the OAuth token that was used to communicate with Cloud Controller will be relayed on the new redirect request. Some blobstores may reject the request in that case. Clients may need to follow the redirect without including the OAuth token.
Only droplets that are in the STAGED
state and have lifecycle type
buildpack
can be downloaded.
Definition
GET /v3/droplets/:guid/download
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Upload droplet bits
Example Request
curl "https://api.example.org/v3/droplets/[guid]/upload" \
-X POST \
-H "Authorization: bearer [token]" \
-F bits=@"droplet.tgz"
Example Response
HTTP/1.1 202 OK
Content-Type: application/json
Location: https://api.example.org/v3/jobs/[guid]
{
"guid": "3c64aba2-2d9e-4eea-9e07-6fec1636315e",
"state": "PROCESSING_UPLOAD",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {}
},
"checksum": null,
"buildpacks": [],
"stack": null,
"image": null,
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"created_at": "2019-05-15T22:43:54Z",
"updated_at": "2019-05-15T22:53:02Z",
"relationships": {
"app": {
"data": {
"guid": "a7c7b09d-350d-4816-bf0b-18612fb2eab4"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/droplets/3c64aba2-2d9e-4eea-9e07-6fec1636315e"
},
"app": {
"href": "https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4"
},
"assign_current_droplet": {
"href": "https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4/relationships/current_droplet",
"method": "PATCH"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Upload a gzip compressed tarball file containing a Cloud Foundry compatible droplet. The file must be sent as part of a multi-part form.
Definition
POST /v3/droplets/:guid/upload
Required parameters
Name | Type | Description |
---|---|---|
bits | form field | A gzip compressed tarball file with .tgz extension containing the droplet bits |
Permitted roles
Admin |
Space Developer |
Environment Variable Groups
There are two types of environment variable groups: running and staging. They are designed to allow platform operators/admins to manage environment variables across all apps in a foundation.
Variables in a running environment variable group will be injected into all running app containers.
Variables in a staging environment variable group will be injected into the staging container for all apps while they are being staged.
The environment variable group object
Example environment variable group object
{
"updated_at": "2016-05-04T17:00:41Z",
"name": "running",
"var": {
"foo": "bar"
},
"links": {
"self": {
"href": "https://api.example.org/v3/environment_variable_groups/running"
}
}
}
Name | Type | Description |
---|---|---|
updated_at | string | The time of last update |
name | string | The name of the group; can only be running or staging |
var | object | Environment variables to inject; keys and values must be strings |
links | links object | Links to related resources |
Get an environment variable group
Example Request
curl "https://api.example.org/v3/environment_variable_groups/[name]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"updated_at": "2016-05-04T17:00:41Z",
"name": "running",
"var": {
"foo": "bar"
},
"links": {
"self": {
"href": "https://api.example.org/v3/environment_variable_groups/running"
}
}
}
Definition
GET /v3/environment_variable_groups/:name
Permitted roles
All Roles |
Update environment variable group
Example Request
curl "https://api.example.org/v3/environment_variable_groups/[name]" \
-X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer [token]" \
-d '{
"var": {
"DEBUG": "false"
"USER": null
}
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"var": {
"RAILS_ENV": "production",
"DEBUG": "false"
},
"links": {
"self": {
"href": "https://api.example.org/v3/environment_variable_groups/[name]"
}
}
}
Update the environment variable group.
The variables given in the request will be merged with the existing environment variable group.
Any requested variables with a value of null
will be removed from the group.
Environment variable names may not start with VCAP_. PORT is not a valid environment variable.
Definition
PATCH /v3/environment_variable_groups/:name
Permitted roles
Admin |
Feature Flags
Feature flags are runtime flags that enable or disable functionality on the API.
The feature flag object
Example Feature Flag object
{
"name": "my_feature_flag",
"enabled": true,
"updated_at": "2016-10-17T20:00:42Z",
"custom_error_message": "error message the user sees",
"links": {
"self": {
"href": "https://api.example.org/v3/feature_flags/my_feature_flag"
}
}
}
Name | Type | Description |
---|---|---|
name | string | The name of the feature flag |
enabled | boolean | Whether the feature flag is enabled |
updated_at | timestamp | The time with zone when the object was last updated; this will be blank for feature flags that have not been configured |
custom_error_message | string | The error string returned by the API when a client performs an action disabled by the feature flag |
links | links object | Links to related resources |
List of feature flags
Name: app_bits_upload Default: true Description: When enabled, space developers can upload app bits. When disabled, only admin users can upload app bits. |
Name: app_scaling Default: true Description: When enabled, space developers can perform scaling operations (i.e. change memory, disk, log rate, or instances). When disabled, only admins can perform scaling operations. |
Name: diego_docker Default: false Description: When enabled, Docker applications are supported by Diego. When disabled, Docker applications will stop running. It will still be possible to stop and delete them and update their configurations. |
Name: env_var_visibility Default: true Description: When enabled, all users can see their environment variables. When disabled, no users can see environment variables. |
Name: hide_marketplace_from_unauthenticated_users Default: false Description: When enabled, service offerings available in the marketplace will be hidden from unauthenticated users. When disabled, unauthenticated users will be able to see the service offerings available in the marketplace. |
Name: private_domain_creation Default: true Description: When enabled, an organization manager can create private domains for that organization. When disabled, only admin users can create private domains. |
Name: resource_matching Default: true Description: When enabled, any user can create resource matches. When disabled, the resource match endpoint always returns an empty array of matches. The package upload endpoint will not cache any uploaded packages for resource matching. |
Name: route_creation Default: true Description: When enabled, a space developer can create routes in a space. When disabled, only admin users can create routes. |
Name: route_sharing (experimental) Default: false Description: When enabled, Space Developers can share routes between two spaces (even across orgs!) in which they have the Space Developer role. When disabled, Space Developers cannot share routes between two spaces. |
Name: service_instance_creation Default: true Description: When enabled, a space developer can create service instances in a space. When disabled, only admin users can create service instances. |
Name: service_instance_sharing Default: false Description: When enabled, Space Developers can share service instances between two spaces (even across orgs!) in which they have the Space Developer role. When disabled, Space Developers cannot share service instances between two spaces. |
Name: set_roles_by_username Default: true Description: When enabled, Org Managers or Space Managers can add access roles by username. In order for this feature to be enabled the CF operator must: 1) Enable the /ids/users/ endpoint for UAA 2) Create a UAA cloud_controller_username_lookup client with the scim.userids authority |
Name: space_developer_env_var_visibility Default: true Description: When enabled, space developers can perform a get on the /v2/apps/:guid/env endpoint, and both space developers and space supporters can perform a get on the /v3/apps/:guid/env and /v3/apps/:guid/environment_variables endpoints. When disabled, neither space developers nor space supporters can access these endpoints. |
Name: space_scoped_private_broker_creation Default: true Description: When enabled, space developers can create space scoped private brokers. When disabled, only admin users can create create space scoped private brokers. |
Name: task_creation Default: true Description: When enabled, space developers can create tasks. When disabled, only admin users can create tasks. |
Name: unset_roles_by_username Default: true Description: When enabled, Org Managers or Space Managers can remove access roles by username. In order for this feature to be enabled the CF operator must: 1) Enable the /ids/users/ endpoint for UAA 2) Create a UAA cloud_controller_username_lookup client with the scim.userids authority |
Name: user_org_creation Default: false Description: When enabled, any user can create an organization via the API. When disabled, only admin users can create organizations via the API. |
Get a feature flag
Example Request
curl "https://api.example.org/v3/feature_flags/[name]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "my_feature_flag",
"enabled": true,
"updated_at": "2016-10-17T20:00:42Z",
"custom_error_message": "error message the user sees",
"links": {
"self": {
"href": "https://api.example.org/v3/feature_flags/my_feature_flag"
}
}
}
Definition
GET /v3/feature_flags/:name
Permitted roles
All Roles |
List feature flags
Example Request
curl "https://api.example.org/v3/feature_flags" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 3,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/feature_flags?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/feature_flags?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/feature_flags?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"name": "my_feature_flag",
"enabled": true,
"updated_at": "2016-10-17T20:00:42Z",
"custom_error_message": "error message the user sees",
"links": {
"self": {
"href": "https://api.example.org/v3/feature_flags/my_feature_flag"
}
}
},
{
"name": "my_second_feature_flag",
"enabled": false,
"updated_at": null,
"custom_error_message": null,
"links": {
"self": {
"href": "https://api.example.org/v3/feature_flags/my_second_feature_flag"
}
}
}
]
}
Retrieve all feature_flags.
Definition
GET /v3/feature_flags
Query parameters
Name | Type | Description |
---|---|---|
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to name ascending; prepend with - to sort descending. Valid value is name |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
Update a feature flag
Example Request
curl "https://api.example.org/v3/feature_flags/[name]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"enabled": true,
"custom_error_message": "error message the user sees"
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "my_feature_flag",
"enabled": true,
"updated_at": "2016-10-17T20:00:42Z",
"custom_error_message": "error message the user sees",
"links": {
"self": {
"href": "https://api.example.org/v3/feature_flags/my_feature_flag"
}
}
}
Definition
PATCH /v3/feature_flags/:name
Optional parameters
Name | Type | Description |
---|---|---|
enabled | boolean | Whether the feature flag is enabled |
custom_error_message | string | The error string returned by the API when a client performs an action disabled by the feature flag |
Permitted roles
Admin |
Info
Info endpoints expose Cloud Controller configuration information.
Get platform info
Example Request
curl "https://api.example.org/v3/info" \
-X GET
Example Response with configured values
HTTP/1.1 200 OK
Content-Type: application/json
{
"build": "afa73e3fe",
"cli_version": {
"minimum": "6.22.0",
"recommended": "latest"
},
"custom": {
"arbitrary": "stuff"
},
"description": "Put your apps here!",
"name": "Cloud Foundry",
"version": 123,
"links": {
"self": { "href": "http://api.example.com/v3/info" } ,
"support": { "href": "http://support.example.com" }
}
}
Example Response with unconfigured values
HTTP/1.1 200 OK
Content-Type: application/json
{
"build": "",
"cli_version": {
"minimum": "",
"recommended": ""
},
"custom": {},
"description": "",
"name": "",
"version": 0,
"links": {
"self": { "href": "http://api.example.com/v3/info" } ,
"support": { "href": "" }
}
}
Definition
GET /v3/info
Authentication
No authentication required.
Get platform usage summary
Example Request
curl "https://api.example.org/v3/info/usage_summary" \
-X GET
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"usage_summary": {
"started_instances": 294,
"memory_in_mb": 123945
},
"links": {
"self": { "href": "http://api.example.com/v3/info/usage_summary" }
}
}
This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation.
Definition
GET /v3/info/usage_summary
Usage summary object
Name | Type | Description |
---|---|---|
started_instances | integer | Total number of process instances in the STARTED state |
memory_in_mb | integer | Sum of memory usage of all tasks in the RUNNING state and all process instances in the STARTED state |
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Isolation Segments
Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.
The isolation segment object
Example Isolation Segment object
{
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
"name": "an_isolation_segment",
"created_at": "2016-10-19T20:25:04Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the isolation segment |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
name | string | Name of the isolation segment |
metadata.labels | labels object | Labels on the isolation segment |
metadata.annotations | annotations object | Annotations on the isolation segment |
links | links object | Links to related resources |
Create an isolation segment
Example Request
curl "https://api.example.org/v3/isolation_segments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "my_segment"
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
"name": "an_isolation_segment",
"created_at": "2016-10-19T20:25:04Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
}
Definition
POST /v3/isolation_segments
Required parameters
Name | Type | Description |
---|---|---|
name | string | Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness |
metadata.labels | label object | Labels applied to the isolation segment |
metadata.annotations | annotation object | Annotations applied to the isolation segment |
Permitted roles
Admin |
Get an isolation segment
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
"name": "an_isolation_segment",
"created_at": "2016-10-19T20:25:04Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
}
Retrieve an isolation segment to which the user has access. For admin, this is any isolation segment in the system. For anyone else, this is an isolation segment in the allowed list for any organization to which the user belongs.
Definition
GET /v3/isolation_segments/:guid
Permitted roles
All Roles |
List isolation segments
Example Request
curl "https://api.example.org/v3/isolation_segments" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 11,
"total_pages": 3,
"first": {
"href": "https://api.example.org/v3/isolation_segments?page=1&per_page=5"
},
"last": {
"href": "https://api.example.org/v3/isolation_segments?page=3&per_page=5"
},
"next": {
"href": "https://api.example.org/v3/isolation_segments?page=2&per_page=5"
},
"previous": null
},
"resources": [
{
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
"name": "an_isolation_segment",
"created_at": "2016-10-19T20:25:04Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
},
{
"guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac",
"name": "an_isolation_segment1",
"created_at": "2016-10-19T20:29:19Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
},
{
"guid": "ecdc67c3-a71e-43ff-bddf-048930b8cd03",
"name": "an_isolation_segment2",
"created_at": "2016-10-19T20:29:22Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
},
{
"guid": "424c89e4-4353-46b7-9bf4-f90bd9bacac0",
"name": "an_isolation_segment3",
"created_at": "2016-10-19T20:29:27Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
},
{
"guid": "0a79fcec-a648-4eb8-a6c3-2b5be39047c7",
"name": "an_isolation_segment4",
"created_at": "2016-10-19T20:29:33Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
}
]
}
Retrieves all isolation segments to which the user has access. For admin, this is all the isolation segments in the system. For anyone else, this is the isolation segments in the allowed list for any organization to which the user belongs.
Definition
GET /v3/isolation_segments
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of isolation segment guids to filter by |
names | list of strings | Comma-delimited list of isolation segment names to filter by |
organization_guids | list of strings | Comma-delimited list of organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at , and name |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
List organizations relationship
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
},
{
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
}
],
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
},
"related": {
"href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/organizations"
}
}
}
This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs.
Definition
GET /v3/isolation_segments/:guid/relationships/organizations
Permitted roles
All Roles |
List spaces relationship
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/spaces" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
},
{
"guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
}
],
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
}
}
}
This endpoint lists the spaces to which the isolation segment is assigned. For an Admin, this will list all associated spaces in the system. For an org manager, this will list only those associated spaces belonging to orgs for which the user is a manager. For any other user, this will list only those associated spaces to which the user has access.
Definition
GET /v3/isolation_segments/:guid/relationships/spaces
Permitted roles
All Roles |
Update an isolation segment
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{ "name": "my_isolation_segment" }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
"name": "my_isolation_segment",
"created_at": "2016-10-19T20:25:04Z",
"updated_at": "2016-11-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
}
},
"metadata": {
"annotations": {},
"labels": {}
}
}
Definition
PATCH /v3/isolation_segments/:guid
Optional parameters
Name | Type | Description |
---|---|---|
name | string | Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness |
metadata.labels | label object | Labels applied to the isolation segment |
metadata.annotations | annotation object | Annotations applied to the isolation segment |
Permitted roles
Admin |
Delete an isolation segment
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
An isolation segment cannot be deleted if it is entitled to any organization.
Definition
DELETE /v3/isolation_segments/:guid
Permitted roles
Admin |
Entitle organizations for an isolation segment
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"data": [
{ "guid":"org-guid-1" },
{ "guid":"org-guid-2" }
]
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
},
{
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
}
],
"links": {
"self": {
"href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
},
"related": {
"href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/organizations"
}
}
}
This endpoint entitles the specified organizations for the isolation segment. In the case where the specified isolation segment is the system-wide shared segment, and if an organization is not already entitled for any other isolation segment, then the shared isolation segment automatically gets assigned as the default for that organization.
Definition
POST /v3/isolation_segments/:guid/relationships/organizations
Required parameters
Name | Type | Description |
---|---|---|
data | to-many relationship | Organization relationships; each organization will be entitled to manage this isolation segment |
Permitted roles
Admin |
Revoke entitlement to isolation segment for an organization
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations/[org_guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
This endpoint revokes the entitlement for the specified organization to the isolation segment. If the isolation segment is assigned to a space within an organization, the entitlement cannot be revoked. If the isolation segment is the organization’s default, the entitlement cannot be revoked.
Definition
DELETE /v3/isolation_segments/:guid/relationships/organizations/:org_guid
Permitted roles
Admin |
Jobs
Jobs are created by the platform when performing certain asynchronous actions.
The job object
Example Job object
{
"guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
"created_at": "2016-10-19T20:25:04Z",
"updated_at": "2016-11-08T16:41:26Z",
"operation": "app.delete",
"state": "COMPLETE",
"links": {
"self": {
"href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
}
},
"errors": [],
"warnings": []
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the job |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
operation | string | Current desired operation of the job on a model |
state | string | State of the job; valid values are PROCESSING , POLLING , COMPLETE , orFAILED |
errors | errors list | Array of errors that occurred while processing the job |
warnings | warnings list | Array of warnings that occurred while processing the job |
links | links object | Links to related resources |
Note: POLLING
happens during asynchronous services operations that require polling the last operation from the service broker.
Get a job
Example Request
curl "https://api.example.org/v3/jobs/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Completed Job Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
"created_at": "2016-10-19T20:25:04Z",
"updated_at": "2016-11-08T16:41:26Z",
"operation": "app.delete",
"state": "COMPLETE",
"links": {
"self": {
"href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
}
},
"errors": [],
"warnings": []
}
Failed Job Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
"created_at": "2016-10-19T20:25:04Z",
"updated_at": "2016-11-08T16:41:26Z",
"operation": "app.delete",
"state": "FAILED",
"links": {
"self": {
"href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
},
"app": {
"href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
}
},
"errors": [
{
"code": 10008,
"title": "CF-UnprocessableEntity",
"detail": "something went wrong"
}
],
"warnings": [
{
"detail": "warning! warning!"
}
]
}
Definition
GET /v3/jobs/:guid
Permitted roles
All Roles |
Manifests
A manifest is a method for applying bulk configurations to apps and their underlying processes.
Manifests are in the YAML format. However, anchors and aliases are not supported.
The manifest schema
Example Manifest
---
version: 1
applications:
- name: app1
buildpacks:
- ruby_buildpack
- java_buildpack
env:
VAR1: value1
VAR2: value2
routes:
- route: route.example.com
- route: another-route.example.com
protocol: http2
services:
- my-service1
- my-service2
- name: my-service-with-arbitrary-params
binding_name: my-binding
parameters:
key1: value1
key2: value2
stack: cflinuxfs4
metadata:
annotations:
contact: "[email protected] [email protected]"
labels:
sensitive: true
processes:
- type: web
command: start-web.sh
disk_quota: 512M
health-check-http-endpoint: /healthcheck
health-check-type: http
health-check-invocation-timeout: 10
instances: 3
memory: 500M
log-rate-limit-per-second: 1KB
timeout: 10
- type: worker
command: start-worker.sh
disk_quota: 1G
health-check-type: process
instances: 2
memory: 256M
log-rate-limit-per-second: 1KB
timeout: 15
- name: app2
env:
VAR1: value1
processes:
- type: web
instances: 1
memory: 256M
log-rate-limit-per-second: 1KB
sidecars:
- name: authenticator
process_types: [ 'web', 'worker' ]
command: bundle exec run-authenticator
memory: 800M
- name: upcaser
process_types: [ 'worker' ]
command: ./tr-server
memory: 2G
Space-level configuration
Name | Type | Description |
---|---|---|
applications | array of app configurations | Configurations for apps in the space |
version | integer | The manifest schema version; currently the only valid version is 1 , defaults to 1 if not provided |
App-level configuration
This configuration is specified per application and applies to all of the application’s processes.
Name | Type | Description |
---|---|---|
name | string | Name of the app |
buildpacks | list of strings | a) An empty array, which will automatically select the appropriate default buildpack according to the coding language b) An array of one or more URLs pointing to buildpacks c) An array of one or more installed buildpack names Replaces the legacy buildpack field |
docker | object | If present, the created app will have Docker lifecycle type; the value of this key is ignored by the API but may be used by clients to source the registry address of the image and credentials, if needed; the generate manifest endpoint will return the registry address of the image and username provided with this key |
env | object | A key-value mapping of environment variables to be used for the app when running |
no-route | boolean | When set to true , any routes specified with the routes attribute will be ignored and any existing routes will be removed |
processes | array of process configurations | List of configurations for individual process types |
random-route | boolean | Creates a random route for the app if true ; if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored regardless of its value |
default-route | boolean | If true, a route for the app will be created using the app name as the hostname and the containing organization’s default domain as the domain; if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored regardless of its value |
routes | array of route configurations | List declaring HTTP and TCP routes to be mapped to the app. |
services | array of service configurations | A list of service-instances to bind to the app |
sidecars | array of sidecar configurations | A list of configurations for individual sidecars |
stack | string | The root filesystem to use with the buildpack, for example cflinuxfs4 |
metadata.labels | label object | Labels applied to the app |
metadata.annotations | annotation object | Annotations applied to the app |
buildpack | string | DEPRECATED in favor of the buildpacks field above |
Process-level configuration
This configuration is for the individual process. Each process is created if it does not already exist.
For backwards compatibility, the web
process configuration may be placed at the top level of the application configuration, rather than listed under processes
. However, if there is a process with type: web
listed under processes
, this configuration will override any at the top level.
Name | Type | Description |
---|---|---|
type | string | (Required) The identifier for the processes to be configured |
command | string | The command used to start the process; this overrides start commands from Procfiles and buildpacks |
disk_quota | string | The disk limit for all instances of the web process; this attribute requires a unit of measurement: B , K , KB , M , MB , G , GB , T , or TB in upper case or lower case |
health-check-http-endpoint | string | Endpoint called to determine if the app is healthy |
health-check-invocation-timeout | integer | The timeout in seconds for individual health check requests for http and port health checks |
health-check-type | string | Type of health check to perform; none is deprecated and an alias to process |
instances | integer | The number of instances to run |
memory | string | The memory limit for all instances of the web process; this attribute requires a unit of measurement: B , K , KB , M , MB , G , GB , T , or TB in upper case or lower case |
log-rate-limit-per-second | string | The log rate limit for all the instances of the process; this attribute requires a unit of measurement: B , K , KB , M , MB , G , GB , T , or TB in upper case or lower case, or -1 or 0 |
timeout | integer | Time in seconds at which the health-check will report failure |
Route-level configuration
This configuration is for creating mappings between the app and a route. Each route is created if it does not already exist. The protocol will be updated for any existing route mapping.
Name | Type | Description |
---|---|---|
route | string | (Required) The route URI. Example: host.domain.com |
protocol | string | Protocol to use for this route. Valid protocols are http1 , http2 , and tcp . |
Service-level configuration
This configuration is creating new service bindings between the app and a service instance. The services
field can
take either an array of service instance name strings or an array of the following service-level fields.
Name | Type | Description |
---|---|---|
name | string | (Required) The name of the service instance to be bound to |
binding_name | string | The name of the service binding to be created |
parameters | object | A map of arbitrary key/value pairs to send to the service broker during binding |
Sidecar-level configuration
This configuration is for the individual sidecar. Each sidecar is created if it does not already exist.
Name | Type | Description |
---|---|---|
name | string | (Required) The identifier for the sidecars to be configured |
command | string | The command used to start the sidecar |
process_types | list of strings | List of processes to associate sidecar with |
memory | integer | Memory in MB that the sidecar will be allocated |
Apply a manifest to a space
Example Request
curl "https://api.example.org/v3/spaces/[guid]/actions/apply_manifest" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/x-yaml" \
--data-binary @/path/to/manifest.yml
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Apply changes specified in a manifest to the named apps and their underlying processes. The apps must reside in the space. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.
Definition
POST /v3/spaces/:guid/actions/apply_manifest
Permitted roles
Admin |
Space Developer |
Generate a manifest for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/manifest" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/x-yaml
---
applications:
- name: my-app
stack: cflinuxfs4
services:
- my-service
routes:
- route: my-app.example.com
protocol: http1
processes:
- type: web
instances: 2
memory: 512M
log-rate-limit-per-second: 1KB
disk_quota: 1024M
health-check-type: http
health-check-http-endpoint: /healthy
health-check-invocation-timeout: 10
health-check-interval: 5
readiness-health-check-type: http
readiness-health-check-http-endpoint: /ready
readiness-health-check-invocation-timeout: 20
readiness-health-check-interval: 5
Generate a manifest for an app and its underlying processes.
Definition
GET /v3/apps/:guid/manifest
Permitted roles
Admin |
Admin Read-Only |
Space Developer |
Create a manifest diff for a space (experimental)
Example Request
curl "https://api.example.org/v3/spaces/[guid]/manifest_diff" \
-X POST \
-H "Content-Type: application/x-yaml" \
-H "Authorization: bearer [token]" \
--data-binary @/path/to/manifest.yml
Example Response
HTTP/1.1 202 OK
Content-Type: application/json
{
"diff": [
{
"op": "remove",
"path": "/applications/0/routes/1",
"was": {"route": "route.example.com"}
},
{
"op": "add",
"path": "/applications/1/buildpacks/2",
"value": "java_buildpack"
},
{
"op": "replace",
"path": "/applications/2/processes/1/memory",
"was": "256M",
"value": "512M"
}
]
}
This endpoint returns a JSON representation of the difference between the provided manifest and the current state of a space.
Currently, this endpoint can only diff version 1 manifests.
The diff object
The diff object format is inspired by the JSON Patch specification.
Name | Type | Description |
---|---|---|
op | string | Type of change; valid values are add , remove , replace |
path | string | Path to changing manifest field |
was | any | For remove and replace operations, the previous value; otherwise key is omitted |
value | any | For add and replace operations, the new value; otherwise key is omitted |
Definition
POST /v3/spaces/:guid/manifest_diff
Permitted roles
Admin |
Space Developer |
Organizations
An org is a development account that an individual or multiple collaborators can own and use. All collaborators access an org with user accounts. Collaborators in an org share a resource quota plan, applications, services availability, and custom domains.
The organization object
Example Organization object
{
"guid": "24637893-3b77-489d-bb79-8466f0d88b52",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "my-organization",
"suspended": false,
"relationships": {
"quota": {
"data": {
"guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
},
"domains": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
},
"default_domain": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
},
"quota": {
"href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the organization |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
name | string | Name of the organization |
suspended | boolean | Whether an organization is suspended or not; non-admins will be blocked from creating, updating, or deleting resources in a suspended organization |
relationships.quota | to-one relationship | The quota applied to the organization |
metadata.labels | label object | Labels applied to the organization |
metadata.annotations | annotation object | Annotations added to the organization |
links | links object | Links to related resources |
Create an organization
Example Request
curl "https://api.example.org/v3/organizations" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{ "name": "my-organization" }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "24637893-3b77-489d-bb79-8466f0d88b52",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "my-organization",
"suspended": false,
"relationships": {
"quota": {
"data": {
"guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
},
"domains": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
},
"default_domain": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
},
"quota": {
"href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
POST /v3/organizations
Required parameters
Name | Type | Description |
---|---|---|
name | string | Organization name |
Optional parameters
Name | Type | Description |
---|---|---|
suspended | boolean | Whether an organization is suspended or not |
metadata.labels | label object | Labels applied to the organization |
metadata.annotations | annotation object | Annotations applied to the organization |
Permitted roles
Admin |
If the user_org_creation
feature flag is enabled, any user with the cloud_controller.write
scope will be able to create organizations.
Get an organization
Example Request
curl "https://api.example.org/v3/organizations/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "24637893-3b77-489d-bb79-8466f0d88b52",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "my-organization",
"suspended": false,
"relationships": {
"quota": {
"data": {
"guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
},
"domains": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
},
"default_domain": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
},
"quota": {
"href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
This endpoint retrieves the specified organization object.
Definition
GET /v3/organizations/:guid
Permitted roles
All Roles |
List organizations
Example Request
curl "https://api.example.org/v3/organizations" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 2,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/organizations?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/organizations?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "org1",
"suspended": false,
"relationships": {
"quota": {
"data": {
"guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"domains": {
"href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains"
},
"default_domain": {
"href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains/default"
},
"quota": {
"href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
"created_at": "2017-02-02T00:14:30Z",
"updated_at": "2017-02-02T00:14:30Z",
"name": "org2",
"suspended": false,
"relationships": {
"quota": {
"data": {
"guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
},
"domains": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains"
},
"default_domain": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains/default"
},
"quota": {
"href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve all organizations the user has access to.
Definition
GET /v3/organizations
Query parameters
Name | Type | Description |
---|---|---|
names | list of strings | Comma-delimited list of organization names to filter by |
guids | list of strings | Comma-delimited list of organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at , and name |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
List organizations for isolation segment
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/organizations" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 2,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/isolation_segments/933b4c58-120b-499a-b85d-4b6fc9e2903b/organizations?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/isolation_segments/933b4c58-120b-499a-b85d-4b6fc9e2903b/organizations?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "org1",
"suspended": false,
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"domains": {
"href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains"
},
"default_domain": {
"href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains/default"
},
"quota": {
"href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
},
"relationships": {
"quota": {
"data": {
"guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
"created_at": "2017-02-02T00:14:30Z",
"updated_at": "2017-02-02T00:14:30Z",
"name": "org2",
"suspended": false,
"relationships": {
"quota": {
"data": {
"guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
},
"domains": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains"
},
"default_domain": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains/default"
},
"quota": {
"href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve the organizations entitled to the isolation segment. Return only the organizations the user has access to.
Definition
GET /v3/isolation_segments/:guid/organizations
Query parameters
Name | Type | Description |
---|---|---|
names | list of strings | Comma-delimited list of organization names to filter by |
guids | list of strings | Comma-delimited list of organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at , and name |
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Auditor |
Org Billing Manager |
Org Manager |
Update an organization
Example Request
curl "https://api.example.org/v3/organizations/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{ "name": "my-organization" }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "24637893-3b77-489d-bb79-8466f0d88b52",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "my-organization",
"suspended": false,
"relationships": {
"quota": {
"data": {
"guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
},
"domains": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
},
"default_domain": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
},
"quota": {
"href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
PATCH /v3/organizations/:guid
Optional parameters
Name | Type | Description |
---|---|---|
name | string | Organization name |
suspended | boolean | Whether an organization is suspended or not |
metadata.labels | label object | Labels applied to the organization |
metadata.annotations | annotation object | Annotations applied to the organization |
Permitted roles
Admin |
Org Manager |
Delete an organization
When an organization is deleted, user roles associated with the organization will also be deleted.
Example Request
curl "https://api.example.org/v3/organizations/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Definition
DELETE /v3/organizations/:guid
Permitted roles
Role | Notes |
---|---|
Admin |
Assign default isolation segment
Example Request
curl "https://api.example.org/v3/organizations/[guid]/relationships/default_isolation_segment" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{
"data": {
"guid": "[iso-seg-guid]"
}
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment"
},
"related": {
"href": "https://api.example.org/v3/isolation_segments/9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
}
}
}
Set the default isolation segment for a given organization. Only isolation segments that are entitled to the organization are eligible to be the default isolation segment.
Definition
PATCH /v3/organizations/:guid/relationships/default_isolation_segment
Required parameters
Name | Type | Description |
---|---|---|
data | to-one relationship | Isolation segment relationship; apps will run in this isolation segment; set data to null to remove the relationship |
Permitted roles
Admin |
Org Manager |
Get default isolation segment
Example Request
curl "https://api.example.org/v3/organizations/[guid]/relationships/default_isolation_segment" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment"
},
"related": {
"href": "https://api.example.org/v3/isolation_segments/9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
}
}
}
Retrieve the default isolation segment for a given organization.
Definition
GET /v3/organizations/:guid/relationships/default_isolation_segment
Permitted roles
All Roles |
Get default domain
Example Request
curl "https://api.example.org/v3/organizations/[guid]/domains/default" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"name": "test-domain.com",
"internal": false,
"router_group": null,
"supported_protocols": ["http"],
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"organization": {
"data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
},
"shared_organizations": {
"data": [
{"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
{"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
]
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
},
"organization": {
"href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
},
"route_reservations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
},
"shared_organizations": {
"href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
}
}
}
Retrieve the default domain for a given organization.
Definition
GET /v3/organizations/:guid/domains/default
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Global Auditor | |
Org Auditor | |
Org Billing Manager | Can only view domains without an organization relationship |
Org Manager | |
Space Auditor | |
Space Developer | |
Space Manager | |
Space Supporter |
Get usage summary
Example Request
curl "https://api.example.org/v3/organizations/[guid]/usage_summary" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"usage_summary": {
"started_instances": 3,
"memory_in_mb": 50,
"routes": 4,
"service_instances": 2,
"reserved_ports": 1,
"domains": 4,
"per_app_tasks": 2,
"service_keys": 1
},
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/usage_summary"
},
"organization": {
"href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
}
}
}
This endpoint retrieves the specified organization object’s memory and app instance usage summary.
Definition
GET /v3/organizations/:guid/usage_summary
Permitted roles
All Roles |
List users for an organization
Example Request
curl "https://api.example.org/v3/organizations/:guid/users" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 3,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/organizations/:guid/users?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/organizations/:guid/users?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/organizations/:guid/users?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "client_id",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"username": null,
"presentation_name": "client_id",
"origin": null,
"metadata": {
"labels": {},
"annotations":{}
},
"links": {
"self": {
"href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
}
}
},
{
"guid": "9da93b89-3f89-4f05-7238-8a2b123c79l9",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"username": "some-name",
"presentation_name": "some-name",
"origin": "uaa",
"metadata": {
"labels": {},
"annotations":{}
},
"links": {
"self": {
"href": "https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9"
}
}
}
]
}
Retrieve all users with a role in the specified organization.
Definition
GET /v3/organizations/:guid/users
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of user guids to filter by |
usernames | list of strings | Comma-delimited list of usernames to filter by. Mutually exclusive with partial_usernames |
partial_usernames | list of strings | Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with usernames |
origins | list of strings | Comma-delimited list of user origins (user stores) to filter by, for example, users authenticated by UAA have the origin “uaa”; users authenticated by an LDAP provider have the origin “ldap”; when filtering by origins, usernames must be included |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at and updated_at |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
Organization Quotas
Organization quotas are named sets of memory, log rate, service, and instance usage quotas. For example, one organization quota might allow up to 10 services, 10 routes, and 2 GB of RAM, while another might offer 100 services, 100 routes, and 10 GB of RAM.
An organization has exactly one organization quota. If not specifically assigned a quota, it will have the default quota.
For more information, see the Cloud Foundry docs.
The organization quota object
Example Organization Quota object
{
"guid": "quota-guid",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:41Z",
"name": "don-quixote",
"apps": {
"total_memory_in_mb": 5120,
"per_process_memory_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"total_instances": 10,
"per_app_tasks": 5
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 4
},
"domains": {
"total_domains": 7
},
"relationships": {
"organizations": {
"data": [
{ "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
]
}
},
"links": {
"self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the organization quota |
created_at | timestamp | The time with zone when the organization quota was created |
updated_at | timestamp | The time with zone when the organization quota was last updated |
name | string | Name of the quota |
apps | object | Quotas that affect applications and application sub-resources |
apps.per_process_memory_in_mb | integer or null |
Maximum memory for a single process or task |
apps.total_memory_in_mb | integer or null |
Total memory allowed for all the started processes and running tasks in an organization |
apps.total_instances | integer or null |
Total instances of all the started processes allowed in an organization |
apps.log_rate_limit_in_bytes_per_second | integer or null |
Total log rate limit allowed for all the started processes and running tasks in an organization |
apps.per_app_tasks | integer or null |
Maximum number of running tasks in an organization |
services | object | Quotas that affect services |
services.paid_services_allowed | boolean | Specifies whether instances of paid service plans can be created |
services.total_service_instances | integer or null |
Total number of service instances allowed in an organization |
services.total_service_keys | integer or null |
Total number of service keys allowed in an organization |
routes | object | Quotas that affect routes |
routes.total_routes | integer or null |
Total number of routes allowed in an organization |
routes.total_reserved_ports | integer or null |
Total number of ports that are reservable by routes in an organization |
domains | object | Quotas that affect domains |
domains.total_domains | integer or null |
Total number of domains that can be scoped to an organization |
relationships.organizations | to-many relationship | A relationship to the organizations where the quota is applied |
links | links object | Links to related resources |
Create an organization quota
Example Request
curl "https://api.example.org/v3/organization_quotas" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "production"
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "quota-guid",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:41Z",
"name": "don-quixote",
"apps": {
"total_memory_in_mb": 5120,
"per_process_memory_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"total_instances": 10,
"per_app_tasks": 5
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 4
},
"domains": {
"total_domains": 7
},
"relationships": {
"organizations": {
"data": [
{ "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
]
}
},
"links": {
"self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
}
}
This endpoint creates a new organization quota, but does not assign it to a specific organization unless an organization GUID is provided in the relationships.organizations
parameter.
To create an organization quota you must be an admin.
Definition
POST /v3/organization_quotas
Required parameters
Name | Type | Description |
---|---|---|
name | string | Name of the quota |
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
apps | object | Quotas that affect applications and application sub-resources | |
apps.per_process_memory_in_mb | integer or null |
Maximum memory for a single process or task | null (infinite) |
apps.total_memory_in_mb | integer or null |
Total memory allowed for all the started processes and running tasks in an organization | null (infinite) |
apps.total_instances | integer or null |
Total instances of all the started processes allowed in an organization | null (infinite) |
apps.log_rate_limit_in_bytes_per_second | integer or null |
Total log rate limit allowed for all the started processes and running tasks in an organization | null (infinite) |
apps.per_app_tasks | integer or null |
Maximum number of running tasks in an organization | null (infinite) |
services | object | Quotas that affect services | |
services.paid_services_allowed | boolean | Specifies whether instances of paid service plans can be created | true |
services.total_service_instances | integer or null |
Total number of service instances allowed in an organization | null (infinite) |
services.total_service_keys | integer or null |
Total number of service keys allowed in an organization | null (infinite) |
routes | object | Quotas that affect routes | |
routes.total_routes | integer or null |
Total number of routes allowed in an organization | null (infinite) |
routes.total_reserved_ports | integer or null |
Total number of ports that are reservable by routes in an organization | null (infinite) |
domains | object | Quotas that affect domains | |
domains.total_domains | integer or null |
Total number of domains that can be scoped to an organization | null (infinite) |
relationships.organizations | to-many relationship | A relationship to the organizations where the quota is applied | [] |
Permitted roles
Admin |
Get an organization quota
Example Request
curl "https://api.example.org/v3/organization_quotas/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "quota-guid",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:41Z",
"name": "don-quixote",
"apps": {
"total_memory_in_mb": 5120,
"per_process_memory_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"total_instances": 10,
"per_app_tasks": 5
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 4
},
"domains": {
"total_domains": 7
},
"relationships": {
"organizations": {
"data": [
{ "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
]
}
},
"links": {
"self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
}
}
This endpoint gets an individual organization quota resource.
Definition
GET /v3/organization_quotas/:guid
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Global Auditor | |
Org Manager | Response will only include guids of managed organizations |
Org Auditor | Response will only include guids of audited organizations |
Org Billing Manager | Response will only include guids of billing-managed organizations |
Space Auditor | Response will only include guids of parent organizations |
Space Developer | Response will only include guids of parent organizations |
Space Manager | Response will only include guids of parent organizations |
Space Supporter | Response will only include guids of parent organizations |
List organization quotas
Example Request
curl "https://api.example.org/v3/organization_quotas" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 2,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/organization_quotas?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/organization_quotas?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "quota-1-guid",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:41Z",
"name": "don-quixote",
"apps": {
"total_memory_in_mb": 5120,
"per_process_memory_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"total_instances": 10,
"per_app_tasks": 5
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 4
},
"domains": {
"total_domains": 7
},
"relationships": {
"organizations": {
"data": [
{ "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
]
}
},
"links": {
"self": { "href": "https://api.example.org/v3/organization_quotas/quota-1-guid" }
}
},
{
"guid": "quota-2-guid",
"created_at": "2017-05-04T17:00:41Z",
"updated_at": "2017-05-04T17:00:41Z",
"name": "sancho-panza",
"apps": {
"total_memory_in_mb": 2048,
"per_process_memory_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"total_instances": 5,
"per_app_tasks": 2
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 4
},
"domains": {
"total_domains": 7
},
"relationships": {
"organizations": {
"data": []
}
},
"links": {
"self": { "href": "https://api.example.org/v3/organization_quotas/quota-2-guid" }
}
}
]
}
This endpoint lists all organization quota resources.
Definition
GET /v3/organization_quotas
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of organization quota guids to filter by |
names | list of strings | Comma-delimited list of organization quota names to filter by |
organization_guids | list of strings | Comma-delimited list of organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Global Auditor | |
Org Manager | Response will only include guids of managed organizations |
Org Auditor | Response will only include guids of audited organizations |
Org Billing Manager | Response will only include guids of billing-managed organizations |
Space Auditor | Response will only include guids of parent organizations |
Space Developer | Response will only include guids of parent organizations |
Space Manager | Response will only include guids of parent organizations |
Space Supporter | Response will only include guids of parent organizations |
Apply an organization quota to an organization
Example Request
curl "https://api.example.org/v3/organization_quotas/:quota_guid/relationships/organizations" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"data": [{ "guid": "org-guid1" }, { "guid": "org-guid2" }]
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": [
{ "guid": "org-guid1" },
{ "guid": "org-guid2" },
{ "guid": "previous-org-guid" }
],
"links": {
"self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid/relationships/organizations" }
}
}
This endpoint applies an organization quota to one or more organizations.
Only admin users can apply an organization quota to an organization.
Definition
POST /v3/organization_quotas/:quota_guid/relationships/organizations
Required parameters
Name | Type | Description |
---|---|---|
data | to-many relationship | Organization guids that the quota will apply to |
Permitted roles
Admin |
Delete an organization quota
Organization quotas cannot be deleted when applied to any organizations.
Example Request
curl "https://api.example.org/v3/organizations_quotas/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Definition
DELETE /v3/organization_quotas/:guid
Permitted roles
Admin |
Update an organization quota
Example Request
curl "https://api.example.org/v3/organization_quotas/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "don-quixote",
"apps": {
"total_memory_in_mb": 5120,
"per_process_memory_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"total_instances": 10,
"per_app_tasks": 5
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20,
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 4
},
"domains": {
"total_domains": 7
}
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "quota-guid",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:41Z",
"name": "don-quixote",
"apps": {
"total_memory_in_mb": 5120,
"per_process_memory_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"total_instances": 10,
"per_app_tasks": 5
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 4
},
"domains": {
"total_domains": 7
},
"relationships": {
"organizations": {
"data": [
{ "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
]
}
},
"links": {
"self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
}
}
This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values.
Definition
PATCH /v3/organization_quotas/:guid
Optional parameters
Name | Type | Description |
---|---|---|
name | string | Name of the quota |
apps | object | Quotas that affect applications and application sub-resources |
apps.per_process_memory_in_mb | integer or null |
Maximum memory for a single process or task |
apps.total_memory_in_mb | integer or null |
Total memory of all the started processes and running tasks in an organization |
apps.total_instances | integer or null |
Total instances of all the started processes in an organization |
apps.log_rate_limit_in_bytes_per_second | integer or null |
Total log rate limit allowed for all the started processes and running tasks in an organization |
apps.per_app_tasks | integer or null |
Maximum number of running tasks in an organization |
services | object | Quotas that affect services |
services.paid_services_allowed | boolean | If instances of paid service plans can be created |
services.total_service_instances | integer or null |
Total number of service instances in an organization |
services.total_service_keys | integer or null |
Total number of service keys in an organization |
routes | object | Quotas that affect routes |
routes.total_routes | integer or null |
Total number of routes that an organization can have |
routes.total_reserved_ports | integer or null |
Total number of ports that all routes in an organization can reserve |
domains | object | Quotas that affect domains |
domains.total_domains | integer or null |
Total number of domains that can be scoped to an organization |
Permitted roles
Admin |
Packages
A package is an application’s ‘source code’; either raw bits for your application or a pointer to these bits.
In Cloud Foundry, packages are staged to produce an executable Droplet. We currently support raw bits and Docker packages.
The package object
Example Package object
{
"guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
"type": "bits",
"data": {
"checksum": {
"type": "sha256",
"value": null
},
"error": null
},
"state": "PROCESSING_UPLOAD",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
},
"upload": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
"method": "POST"
},
"download": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
"method": "GET"
},
"app": {
"href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the package |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
type | string | Package type; valid values are bits , docker |
data | object | Data for package type (see below) |
state | string | State of the package; valid states are AWAITING_UPLOAD , PROCESSING_UPLOAD , READY , FAILED , COPYING , EXPIRED |
relationships.app | to-one relationship | The app the package belongs to |
metadata.labels | label object | Labels applied to the package |
metadata.annotations | annotation object | Annotations applied to the package |
links | links object | Links to related resources |
Bits package data
A bits package is used to upload source code for an app to. The bits package will provide an upload
link to which a zip file should be uploaded.
Name | Type | Description |
---|---|---|
data.error | string | If an error occurs this field will contain the error message |
data.checksum.type | string | The checksum type, for example: sha256 |
data.checksum.value | string | The checksum value; this will be populated after bits are uploaded |
Docker package data
A Docker package references a Docker image from a registry.
Name | Type | Description |
---|---|---|
data.image | string | The registry address of the image |
data.username | string | The username for the image’s registry |
data.password | string | The password for the image’s registry |
Create a package
Example Request (buildpack app)
curl "https://api.example.org/v3/packages" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"type": "bits",
"relationships": {
"app": {
"data": {
"guid": "[guid]"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
"type": "bits",
"data": {
"checksum": {
"type": "sha256",
"value": null
},
"error": null
},
"state": "PROCESSING_UPLOAD",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
},
"upload": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
"method": "POST"
},
"download": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
"method": "GET"
},
"app": {
"href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Example Request (Docker app)
curl "https://api.example.org/v3/packages" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"type": "docker",
"relationships": {
"app": {
"data": {
"guid": "[guid]"
}
}
},
"data": {
"image": "registry/image:latest",
"username": "username",
"password": "password"
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "4cb65058-f04f-458f-aca1-5f4e43de6407",
"type": "docker",
"data": {
"image": "registry/image:latest",
"username": "username",
"password": "***"
},
"state": "READY",
"created_at": "2015-11-03T00:53:54Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "d8b8148d-5798-44de-821a-64b85b15e968"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/4cb65058-f04f-458f-aca1-5f4e43de6407"
},
"app": {
"href": "https://api.example.org/v3/apps/d8b8148d-5798-44de-821a-64b85b15e968"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
POST /v3/packages
Required parameters
Name | Type | Description |
---|---|---|
type | string | Type of the package; valid values are bits , docker |
relationships.app | to-one relationship | A relationship to an app |
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
data | object | Data for package type | {} |
Conditional Parameters
Name | Type | Description |
---|---|---|
data.image | string | Required when type is docker ; the registry address of the image |
data.username | string | Optional when type is docker and accessing a secured registry |
data.password | string | Optional when type is docker and accessing a secured registry |
metadata.labels | label object | Labels applied to the package |
metadata.annotations | annotation object | Annotations applied to the package |
Permitted roles
Admin |
Space Developer |
Get a package
Example Request
curl "https://api.example.org/v3/packages/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
"type": "bits",
"data": {
"checksum": {
"type": "sha256",
"value": null
},
"error": null
},
"state": "PROCESSING_UPLOAD",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
},
"upload": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
"method": "POST"
},
"download": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
"method": "GET"
},
"app": {
"href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
GET /v3/packages/:guid
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
List packages
Example Request
curl "https://api.example.org/v3/packages" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 2,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "a57fd932-85db-483a-a27e-b00efbb3b0a4",
"type": "bits",
"data": {
"checksum": {
"type": "sha256",
"value": null
},
"error": null
},
"state": "AWAITING_UPLOAD",
"created_at": "2015-11-03T00:53:54Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "fa3558ce-1c4d-46fc-9776-54b9c8021745"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4"
},
"upload": {
"href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/upload",
"method": "POST"
},
"download": {
"href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/download",
"method": "GET"
},
"app": {
"href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691",
"type": "docker",
"data": {
"image": "registry/image:latest",
"username": "username",
"password": "***"
},
"state": "READY",
"created_at": "2015-11-03T00:53:54Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "fa3558ce-1c4d-46fc-9776-54b9c8021745"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691"
},
"app": {
"href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve all packages the user has access to.
Definition
GET /v3/packages
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of package guids to filter by |
states | list of strings | Comma-delimited list of package states to filter by |
types | list of strings | Comma-delimited list of package types to filter by |
app_guids | list of strings | Comma-delimited list of app guids to filter by |
space_guids | list of strings | Comma-delimited list of space guids to filter by |
organization_guids | list of strings | Comma-delimited list of organization guids to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at |
label_selector | string | A query string containing a list of label selector requirements |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
All Roles |
List packages for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/packages" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"pagination": {
"total_results": 1,
"total_pages": 1,
"first": {
"href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "752edab0-2147-4f58-9c25-cd72ad8c3561",
"type": "bits",
"data": {
"error": null,
"checksum": {
"type": "sha256",
"value": null
}
},
"state": "READY",
"created_at": "2016-03-17T21:41:09Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "f2efe391-2b5b-4836-8518-ad93fa9ebf69"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561"
},
"upload": {
"href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/upload",
"method": "POST"
},
"download": {
"href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/download",
"method": "GET"
},
"app": {
"href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve packages for an app that the user has access to.
Definition
GET /v3/apps/:guid/packages
Query parameters
Name | Type | Description |
---|---|---|
guids | list of strings | Comma-delimited list of package guids to filter by |
states | list of strings | Comma-delimited list of package states to filter by |
types | list of strings | Comma-delimited list of package types to filter by |
page | integer | Page to display; valid values are integers >= 1 |
per_page | integer | Number of results per page; valid values are 1 through 5000 |
order_by | string | Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at , updated_at |
created_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
updated_ats | timestamp | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators |
Permitted roles
Admin |
Admin Read-Only |
Global Auditor |
Org Manager |
Space Auditor |
Space Developer |
Space Manager |
Space Supporter |
Update a package
Example Request
curl "https://api.example.org/v3/packages/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
"type": "bits",
"data": {
"checksum": {
"type": "sha256",
"value": null
},
"error": null
},
"state": "PROCESSING_UPLOAD",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
},
"upload": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
"method": "POST"
},
"download": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
"method": "GET"
},
"app": {
"href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
PATCH /v3/packages/:guid
Optional parameters
Name | Type | Description |
---|---|---|
metadata.labels | label object | Labels applied to the package |
metadata.annotations | annotation object | Annotations applied to the package |
username | string | The username for the image’s registry. Only possible for Docker package. |
password | string | The password for the image’s registry. Only possible for Docker package. |
Permitted roles
Admin |
Space Developer |
Delete a package
Example Request
curl "https://api.example.org/v3/packages/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Definition
DELETE /v3/packages/:guid
Permitted roles
Admin |
Space Developer |
Copy a package
Example Request
curl "https://api.example.org/v3/packages?source_guid=[guid]" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{
"relationships": {
"app": {
"data": {
"guid": "[destination-app-guid]"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "fec72fc1-e453-4463-a86d-5df426f337a3",
"type": "docker",
"data": {
"image": "http://awesome-sauce.example.org"
},
"state": "COPYING",
"created_at": "2016-03-17T21:41:09Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "36208a68-562d-4f51-94ea-28bd8553a271"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3"
},
"app": {
"href": "https://api.example.org/v3/apps/36208a68-562d-4f51-94ea-28bd8553a271"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
This endpoint copies the bits of a source package to a target package.
Definition
POST /v3/packages?source_guid=:guid
Required query parameters
Name | Type | Description |
---|---|---|
source_guid | uuid | GUID of the source package to copy from |
Required parameters
Name | Type | Description |
---|---|---|
relationships.app | to-one relationship | A relationship to the destination app |
Permitted roles
Admin |
Space Developer |
Download package bits
Example Request
curl "https://api.example.org/v3/packages/[guid]/download" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 302 Found
You are being redirected.
This endpoint downloads the bits of an existing package.
When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits.
If the client is automatically following redirects, then the OAuth token that was used to communicate
with Cloud Controller will be replayed on the new redirect request. Some blobstores may reject
the request in that case. Clients may need to follow the redirect without including the OAuth token.
Definition
GET /v3/packages/:guid/download
Permitted roles
Admin |
Space Developer |
Stage a package
Staging a package is accomplished by creating a build. See Create a build.
Upload package bits
Example Request
curl "https://api.example.org/v3/packages/[guid]/upload" \
-X POST \
-H "Authorization: bearer [token]" \
-F bits=@"package.zip" \
-F resources='[{"path":"path/to/content.txt","size_in_bytes":123,"checksum": {"value": "b907173290db6a155949ab4dc9b2d019dea0c901"}},{"path":"path/to/code.jar","size_in_bytes":123,"checksum": {"value": "ff84f89760317996b9dd180ab996b079f418396f"}},{"path":"path/to/code.jar","size_in_bytes":123,"checksum": {"value": "ff84f89760317996b9dd180ab996b079f418396f"},"mode":"644"}]'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
"type": "bits",
"data": {
"checksum": {
"type": "sha256",
"value": null
},
"error": null
},
"state": "PROCESSING_UPLOAD",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"app": {
"data": {
"guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
},
"upload": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
"method": "POST"
},
"download": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
"method": "GET"
},
"app": {
"href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
This upload endpoint takes a multi-part form requests for packages of type bits
. The request requires either a .zip file uploaded under the bits
field or a list of resource match objects under the resources
field. These field may be used together.
The resources
field in the request accepts the v2 resources object format.
Definition
POST /v3/packages/:guid/upload
Optional parameters
Name | Type | Description | Default |
---|---|---|---|
bits | form field | A binary zip file containing the package bits | |
resources | form field | Fingerprints of the application bits that have previously been pushed to Cloud Foundry, formatted as resource match objects | [] |
Permitted roles
Admin |
Space Developer |
Processes
Processes define the runnable units of an app. An app can have multiple process types, each with differing commands and scale. Processes for an app are defined by the buildpack used to stage the app and can be customized by including a Procfile in the application source.
Web process type
- By default, a newly created app will come with one instance of the
web
process and all other process types are scaled to zero - Scale the
web
process to zero if it is not required for your app - Unless otherwise specified, all routes will be mapped to the
web
process by default
The process object
Example Process object
{
"guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
"type": "web",
"command": "rackup",
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"health_check": {
"type": "port",
"data": {
"timeout": null
}
},
"readiness_health_check": {
"type": "process",
"data": {
"invocation_timeout": null
}
},
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
},
"revision": {
"data": {
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
},
"created_at": "2016-03-23T18:48:22Z",
"updated_at": "2016-03-23T18:48:42Z",
"version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
"links": {
"self": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
},
"scale": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
"method": "POST"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
}
}
}
Name | Type | Description |
---|---|---|
guid | uuid | Unique identifier for the process |
created_at | timestamp | The time with zone when the object was created |
updated_at | timestamp | The time with zone when the object was last updated |
version | uuid | Random identifier that changes every time the process will be recreated in the runtime. |
type | string | Process type; a unique identifier for processes belonging to an app |
command | string or null | The command used to start the process; use null to revert to the buildpack-detected or procfile-provided start command |
instances | integer | The number of instances to run |
memory_in_mb | integer | The memory in MB allocated per instance |
log_rate_limit_in_bytes_per_second | integer | The log rate in bytes per second allocated per instance |
disk_in_mb | integer | The disk in MB allocated per instance |
health_check | health check object | The health check to perform on the process |
readiness_health_check | readiness health check object | The readiness health check to perform on the process |
relationships.app | to-one relationship | The app the process belongs to |
relationships.revision | to-one relationship | The app revision the process is currently running |
metadata.labels | label object | Labels applied to the process |
metadata.annotations | annotation object | Annotations applied to the process |
links | links object | Links to related resources |
The health check object
Example health check object
{
"type": "port",
"data": {
"timeout": null
}
}
Name | Type | Description |
---|---|---|
type | string | The type of health check to perform; valid values are http , port , and process ; default is port |
data.timeout | integer | The duration in seconds that health checks can fail before the process is restarted |
data.invocation_timeout | integer | The timeout in seconds for individual health check requests for http and port health checks |
data.interval | integer | The interval in seconds between health check requests |
data.endpoint | string | The endpoint called to determine if the app is healthy; this key is only present for http health checks |
The readiness health check object
Example readiness health check object
{
"type": "http",
"data": {
"endpoint": "/ready",
"invocation_timeout": 2
}
}
Name | Type | Description |
---|---|---|
type | string | The type of health check to perform; valid values are http , port , and process ; default is process |
data.invocation_timeout | integer | The timeout in seconds for individual health check requests for http and port health checks |
data.interval | integer | The interval in seconds between health check requests |
data.endpoint | string | The endpoint called to determine if the app is ready; this key is only present for http health checks |
The process stats object
The process stats object provides information about the status of an individual instance of a process.
Example process stats object
{
"type": "web",
"index": 0,
"state": "RUNNING",
"usage": {
"time": "2016-03-23T23:17:30.476314154Z",
"cpu": 0.00038711029163348665,
"cpu_entitlement": 0.01117396940977856,
"mem": 19177472,
"disk": 69705728,
"log_rate": 0
},
"host": "10.244.16.10",
"instance_ports": [
{
"external": 64546,
"internal": 8080,
"external_tls_proxy_port": 61002,
"internal_tls_proxy_port": 61003
}
],
"uptime": 9042,
"mem_quota": 268435456,
"disk_quota": 1073741824,
"fds_quota": 16384,
"isolation_segment": "example_iso_segment",
"details": null
}
Name | Type | Description |
---|---|---|
type | string | Process type; a unique identifier for processes belonging to an app |
index | integer | The zero-based index of running instances |
state | string | The state of the instance; valid values are RUNNING , CRASHED , STARTING , DOWN |
routable | boolean | Whether or not the instance is routable (determined by the readiness check of the app). If app readiness checks and routability are unsupported by Diego, this will return as null . |
usage | object | Object containing actual usage data for the instance; the value is {} when usage data is unavailable |
usage.time | timestamp | The time when the usage was requested |
usage.cpu | number | The current cpu usage of the instance |
usage.mem | integer | The current memory usage of the instance |
usage.disk | integer | The current disk usage of the instance |
usage.log_rate | integer | The current logging usage of the instance |
host | string | The host the instance is running on |
instance_internal_ip | string | The internal IP address of the instance |
instance_ports | object | JSON array of port mappings between the network-exposed port used to communicate with the app (external ) and port opened to the running process that it can listen on (internal ) |
uptime | integer | The uptime in seconds for the instance |
mem_quota | integer | The current maximum memory allocated for the instance; the value is null when memory quota data is unavailable |
disk_quota | integer | The current maximum disk allocated for the instance; the value is null when disk quota data is unavailable |
log_rate_limit | integer | The current maximum log rate allocated for the instance; the value -1 is unlimited, the value is null when the log_rate_limit is unavailable |
fds_quota | integer | The maximum file descriptors the instance is allowed to use |
isolation_segment | string | The current isolation segment that the instance is running on; the value is null when the instance is not placed on a particular isolation segment |
details | string | Information about errors placing the instance; the value is null if there are no placement errors |
Get a process
Example Request
curl "https://api.example.org/v3/processes/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
"type": "web",
"command": "rackup",
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"health_check": {
"type": "port",
"data": {
"timeout": null
}
},
"readiness_health_check": {
"type": "process",
"data": {
"invocation_timeout": null
}
},
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
},
"revision": {
"data": {
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
},
"created_at": "2016-03-23T18:48:22Z",
"updated_at": "2016-03-23T18:48:42Z",
"version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
"links": {
"self": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
},
"scale": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
"method": "POST"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
}
}
}
Definition
GET /v3/processes/:guid
GET /v3/apps/:guid/processes/:type
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Global Auditor | Some fields are redacted |
Org Manager | Some fields are redacted |
Space Auditor | Some fields are redacted |
Space Developer | |
Space Manager | Some fields are redacted |
Space Supporter | Some fields are redacted |
Get stats for a process
Process stats are objects that represent the individual instances of a process.
Example Request
curl "https://api.example.org/v3/processes/[guid]/stats" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"resources": [
{
"type": "web",
"index": 0,
"state": "RUNNING",
"usage": {
"time": "2016-03-23T23:17:30.476314154Z",
"cpu": 0.00038711029163348665,
"cpu_entitlement": 0.01117396940977856,
"mem": 19177472,
"disk": 69705728,
"log_rate": 0
},
"host": "10.244.16.10",
"instance_internal_ip": "10.255.93.167",
"instance_ports": [
{
"external": 64546,
"internal": 8080,
"external_tls_proxy_port": 61002,
"internal_tls_proxy_port": 61003
}
],
"uptime": 9042,
"mem_quota": 268435456,
"disk_quota": 1073741824,
"fds_quota": 16384,
"isolation_segment": "example_iso_segment",
"log_rate_limit": null,
"details": null
},
{
"type": "web",
"index": 1,
"state": "STARTING",
"usage": {
"cpu": 0,
"cpu_entitlement": null,
"disk": 0,
"log_rate": 0,
"mem": 0,
"time": "2016-03-23T21:34:04+00:00"
},
"disk_quota": null,
"fds_quota": 16384,
"host": "",
"instance_internal_ip": "",
"instance_ports": null,
"isolation_segment": null,
"log_rate_limit": null,
"mem_quota": null,
"uptime": 0,
"details": null
}
]
}
Definition
GET /v3/processes/:guid/stats
GET /v3/apps/:guid/processes/:type/stats
Permitted roles
Role | Notes |
---|---|
Admin | |
Admin Read-Only | |
Global Auditor | Some fields are redacted |
Org Manager | Some fields are redacted |
Space Auditor | Some fields are redacted |
Space Developer | |
Space Manager | Some fields are redacted |
Space Supporter | Some fields are redacted |
List processes
Example Request
curl "https://api.example.org/v3/processes" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_results": 3,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/processes?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/processes?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/processes?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
"type": "web",
"command": "[PRIVATE DATA HIDDEN IN LISTS]",
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"health_check": {
"type": "port",
"data": {
"timeout": null,
"invocation_timeout": null,
"interval": null
}
},
"readiness_health_check": {
"type": "process",
"data": {
"invocation_timeout": null,
"interval": null
}
},
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
},
"revision": {
"data": {
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
},
"created_at": "2016-03-23T18:48:22Z",
"updated_at": "2016-03-23T18:48:42Z",
"version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
"links": {
"self": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
},
"scale": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
"method": "POST"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
}
}
},
{
"guid": "3fccacd9-4b02-4b96-8d02-8e865865e9eb",
"type": "worker",
"command": "[PRIVATE DATA HIDDEN IN LISTS]",
"instances": 1,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"log_rate_limit_in_bytes_per_second": 1024,
"health_check": {
"type": "process",
"data": {
"invocation_timeout":