Introduction
Overview
Welcome to the Cloud Foundry V3 API docs! Version 3 will add 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
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 the primary API 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 | datetime | The ISO8601 compatible date and time when resource was created. |
| updated_at | datetime | 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": "GET"
}
| 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 OAuth2 Token with User Roles that are managed by the API.
OAuth2 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 Foundry user roles
| 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 a 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 |
Errors
Example Error
{
"errors": [
{
"code": 10008,
"title": "CF-UnprocessableEntity",
"detail": "something went wrong"
}
]
}
An error response will always return a list of error objects in the errors field.
The error object
| Name | Type | Description |
|---|---|---|
| code | integer | A numeric code for this error. |
| title | string | Short description of the error. |
| detail | string | Detailed description of the error. |
Filters
Endpoints which return lists of resources also support filtering the returned resources using query parameters. The available filter parameters are described in a resource’s “list” endpoint in the section “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.
Multiple value request #2
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=cflinuxfs3
This will return all apps with name the_name AND stack cflinuxfs3.
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?paths=pepper,,tabi
This will return all routes with path "pepper", "" OR "tabi".
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 |
| routes/[:guid] | domain |
| 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
// rest of pagination omitted
},
"resources": [
{
"guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
"name": "app1"
// rest omitted
},
{
"guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
"name": "app2"
// rest omitted
}
],
"included": {
"spaces": [
{
"guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
"name": "space1"
// rest of info on space1 omitted
},
{
"guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
"name": "space2"
// rest of info on space2 omitted
}
],
"organizations": [
{
"guid": "b2075a71-28b6-411a-a896-56f75d892f58",
"name": "org1"
// rest of info on org1 omitted
},
{
"guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
"name": "org2"
// rest of info on org2 omitted
}
]
}
}
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"
// ...
}
]
}
}
Example request for all spaces including their parent organizations
curl "https://api.example.org/v3/spaces?include=organization" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
{
"pagination": {
"total_results": 4,
"total_pages": 1,
// ...
},
"resources": [
{
"guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
"name": "space"
// ...
},
{
"guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
"name": "space1a"
// ...
},
{
"guid": "615e724a-dfae-4846-836b-8c413f6192cd",
"name": "space1b"
// ...
},
{
"guid": "5801b8dd-5ca6-41bb-ba23-690e703c631a",
"name": "space2a"
// ...
}
],
"included": {
"organizations": [
{
"guid": "b2075a71-28b6-411a-a896-56f75d892f58",
"name": "org"
// ...
},
{
"guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
"name": "org1"
// ...
},
{
"guid": "c4bf7e09-57e7-453c-8b8e-fbebc986201e",
"name": "org2"
// ...
}
]
}
}
Lifecycles
Lifecycles inform the platform of how to build droplets and run apps. For example the
buildpack lifecycle will use a droplet and a rootfs to run the app, while 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": "cflinuxfs3"
}
}
This is the default lifecycle for Cloud Foundry. 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.
Buildpack lifecycle object
| Name | Type | Description |
|---|---|---|
| type | string | buildpack |
| data.buildpacks | array of strings | A list of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack. |
| data.stack | string | The root filesystem to use with the buildpack, for example cflinuxfs3 |
Docker lifecycle
Example Docker Lifecycle
{
"type": "docker",
"data": {}
}
This allows Cloud Foundry to run 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.
Examples may include (but are not limited to):
"contact info": "bob@example.com jane@example.com""library versions": "Spring: 5.1, Redis Client: a184098. yaml parser: 38""git-sha": "d56fe0367554ae5e878e37ed6c5b9a82f5995512"
Annotation key
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.
A annotation key prefix must adhere to the following restrictions:
- Length: 0-253 characters
- Allowed characters: alphanumeric,
-, and. - DNS subdomain format (series of subdomain annotations separated by
.)
A annotation 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
Annotation value
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 false.
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.
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
nullvalue - 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_TYPEdefines the type of the process.COMMANDis 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.
Relationships
Relationships represent associations between resources. They can be used to create, read, update, and delete these associations. For example, an app has a relationship to a space (every app belongs in one space); a space has a relationship with an organization (every space belongs in one organization).
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 listed below. See the docs for each resource to see how it interacts with its relationships.
Many endpoints return the status of its relationships. For example, GET
/v3/spaces/:guid returns a JSON response with a relationships key with the
GUID of the organization to which the space belongs.
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. |
| 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. |
Resources
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": "cflinuxfs3"
}
},
"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 |
|---|---|---|
| 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. |
| guid | uuid | Unique identifier for the app. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| relationships.space (experimental) | to-one relationship | The space the app is contained in. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the app. |
| metadata.annotations (experimental) | annotation object | Annotations added to the app. |
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": "cflinuxfs3"
}
},
"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 (experimental) | label object | Labels applied to the app. | |
| metadata.annotations (experimental) | annotation object | Annotations applied to the app. |
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": "cflinuxfs3"
}
},
"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 | string | Experimental - 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 |
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": "cflinuxfs3"
}
},
"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": "cflinuxfs3"
}
},
"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. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
| include | string | Experimental - Optionally include a list of unique related resources in the response. Valid values are space and space.organization |
| lifecycle_type | string | Lifecycle type to filter by. Valid values are buildpack, docker. |
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": "cflinuxfs3"
}
},
"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 (experimental) | label object | Labels applied to the app. |
| metadata.annotations (experimental) | 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": "cflinuxfs3",
"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"
}
},
"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 |
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 |
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",
"label": "mysql",
"tags": ["relational", "sql"],
"plan": "xlarge",
"credentials": {
"username": "user",
"password": "top-secret"
},
"syslog_drain_url": "https://syslog.example.org/drain",
"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
| Admin |
| Admin Read-Only |
| Space Developer |
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 |
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 |
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 |
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": "cflinuxfs3"
}
},
"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 |
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": "cflinuxfs3"
}
},
"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 |
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 |
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
| 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 |
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 (experimental)",
"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 |
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
| Admin |
| Space Developer |
Audit Events
Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions.
For more information and a list of all possible event types, see the Cloud Foundry docs.
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. |
| 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 | |
| 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. |
| Org Auditor | Cannot see events which occurred in orgs 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. |
| 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. |
Permitted roles
| Admin Read-Only |
| Admin |
| Global Auditor |
| Org Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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": "bill@example.com"
},
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs3"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": {
"guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
"href": "https://api.example.org/v3/droplets/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"
}
}
}
| Name | Type | Description |
|---|---|---|
| state | string | State of the build. Valid states are STAGING, STAGED, or FAILED. |
| 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 | object | The package that is the input to the staging process. |
| droplet | object | A resulting droplet from the staging process. |
| guid | uuid | Unique identifier for the build. |
| created_at | datetime | The time with zone when the build was created. |
| updated_at | datetime | The time with zone when the build was last updated. |
| created_by | object | The user that created the build. |
| relationships.app (experimental) | to-one relationship | The app the build belongs to. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the build. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the build. |
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": "bill@example.com"
},
"state": "STAGING",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs3"
}
},
"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 |
| metadata.labels (experimental) | label object | Labels applied to the build. | |
| metadata.annotations (experimental) | annotation object | Annotations applied to the build. |
Permitted roles
| Admin |
| Space Developer |
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": "bill@example.com"
},
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs3"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": {
"guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
"href": "https://api.example.org/v3/droplets/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"
}
}
}
Definition
GET /v3/builds/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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": "bill@example.com"
},
"state": "STAGING",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs3"
}
},
"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 | Experimental - A query string containing a list of label selector requirements. |
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": "bill@example.com"
},
"state": "STAGING",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs3"
}
},
"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 | Experimental - 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 |
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": "bill@example.com"
},
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs3"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": {
"guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
"href": "https://api.example.org/v3/droplets/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"
}
}
}
Definition
PATCH /v3/builds/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the build. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the build. |
Permitted roles
| Admin |
| Space Developer |
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 | datetime | The time with zone when the object was created. |
| updated_at | datetime | 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 value is: AWAITING_UPLOAD |
| filename | string | The filename 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 can be used for staging |
| locked | boolean | Whether or not the buildpack is locked to prevent updating the bits |
| 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 (experimental) | label object | Labels applied to the buildpack. | |
| metadata.annotations (experimental) | 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 | Experimental - A query string containing a list of label selector requirements. |
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 (experimental) | label object | Labels applied to the buildpack. |
| metadata.annotations (experimental) | 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",
"state": "DEPLOYING",
"status": {
"value": "ACTIVE",
"reason": "DEPLOYING"
},
"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"
}
}
}
| Name | Type | Description |
|---|---|---|
| state | string | (deprecated) The state of the deployment. Valid values are DEPLOYING, DEPLOYED, CANCELING, or CANCELED. This field will be removed in the future; use the status fields to determine deployment state instead. |
| 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- CANCELING2. If status.value is FINALIZED- DEPLOYED- CANCELED- SUPERSEDED (another deployment created for app before completion)- DEGENERATE (the deployment was created incorrectly by the system) |
| strategy | string | Strategy used for the deployment. Supported strategies are rolling only. |
| guid | uuid | Unique identifier for the deployment. |
| relationships.app | to-one relationship | The app the deployment is updating. |
| droplet | object | The droplet the deployment is transitioning the app to. |
| previous_droplet | object | The app’s current droplet 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. |
| metadata.labels (experimental) | label object | Labels applied to the deployment. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the deployment. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| 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",
"state": "DEPLOYING",
"status": {
"value": "ACTIVE",
"reason": "DEPLOYING"
},
"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"
}
}
}
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 (experimental) | label object | Labels applied to the deployment. | |
| metadata.annotations (experimental) | annotation object | Annotations applied to the deployment. |
1 Only a droplet or a revision may be provided, not both.
Permitted roles
| Admin |
| Space Developer |
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",
"state": "DEPLOYING",
"status": {
"value": "ACTIVE",
"reason": "DEPLOYING"
},
"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"
}
}
}
Definition
GET /v3/deployments/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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",
"state": "DEPLOYED",
"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, and DEGENERATE. |
| 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 | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| Admin Read-Only |
| Admin |
| Global Auditor |
| Org Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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",
"state": "DEPLOYING",
"status": {
"value": "ACTIVE",
"reason": "DEPLOYING"
},
"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"
}
}
}
Definition
PATCH /v3/deployments/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the deployment. |
| metadata.annotations (experimental) | 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 |
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,
"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 | datetime | The time with zone when the object was created. |
| updated_at | datetime | 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. |
| 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. |
| 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. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the domain. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the domain. |
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,
"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. | false |
| organization | to-one relationship | A relationship to the organization the domain will be scoped to. Note: can not be used when internal is set to true |
|
| shared_organizations | to-many relationship | A relationship to organizations the domain will be shared with. Note: can not be used without an organization relationship |
|
| metadata.labels (experimental) | label object | Labels applied to the domain. | |
| metadata.annotations (experimental) | 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,
"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
| Roles | Notes |
|---|---|
| Admin Read-Only | |
| Admin | |
| Global Auditor | |
| Org Auditor | |
| Org Billing Manager | Can only view domains without an organization relationship. |
| Org Manager | |
| Space Auditor | |
| Space Developer | |
| Space Manager |
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,
"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"
}
}
}
]
}
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. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
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/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,
"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"
}
}
}
]
}
Retrieve all domains available in an organization for the current user. This will return user-visible domains without an organization relationship AND domains scoped or shared with the organization.
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. |
| label_selector | string | Experimental - 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,
"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 (experimental) | label object | Labels applied to the domain. | |
| metadata.annotations (experimental) | 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
| Role | Notes |
|---|---|
| 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": "cflinuxfs3",
"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"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
| Name | Type | Description |
|---|---|---|
| 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. |
| guid | uuid | Unique identifier for the droplet. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| relationships.app (experimental) | to-one relationship | The app the droplet belongs to. |
| links | links object | Links to related resources. |
| 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. |
| metadata.labels (experimental) | labels object | Labels on the droplet |
| metadata.annotations (experimental) | annotations object | Annotations on the droplet |
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 cflinuxfs3 |
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": "cflinuxfs3",
"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": "cflinuxfs3",
"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"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
GET /v3/droplets/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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": "cflinuxfs3",
"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"
}
},
"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 | Experimental - A query string containing a list of label selector requirements. |
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": "cflinuxfs3",
"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"
}
},
"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 | Experimental - 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 |
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": "cflinuxfs3",
"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"
}
},
"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 | Experimental - 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 |
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": "cflinuxfs3",
"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"
}
},
"metadata": {
"labels": {
"release": "stable"
},
"annotations": {
"note": "detailed information"
}
}
}
Definition
PATCH /v3/droplets/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the droplet. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the droplet. |
Permitted roles
| Admin |
| Org Manager |
| Space Developer |
| Space Manager |
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 |
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 |
|---|---|---|
| name | string | The name of the group. Can only be running or staging. |
| updated_at | string | The time of last update. |
| 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 | datetime | 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_uploadDefault: true Description: When enabled, space developers can upload app bits. When disabled, only admin users can upload app bits. |
Name: app_scalingDefault: true Description: When enabled, space developers can perform scaling operations (i.e. change memory, disk or instances). When disabled, only admins can perform scaling operations. |
Name: diego_dockerDefault: 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_visibilityDefault: true Description: When enabled, all users can see their environment variables. When disabled, no users can see environment variables. |
Name: hide_marketplace_from_unauthenticated_usersDefault: 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_creationDefault: 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_matchingDefault: true Description: When enabled, any user can create resource matches. When disabled, the resource match endpoint always returns an empty array of matches. |
Name: route_creationDefault: true Description: When enabled, a space developer can create routes in a space. When disabled, only admin users can create routes. |
Name: service_instance_creationDefault: 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_sharingDefault: 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_usernameDefault: 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_visibilityDefault: true Description: When enabled, space developers can do a get on the /v2/apps/:guid/env and /v3/apps/:guid/env end points. When disabled, space developers can no longer do a get against these end points. |
Name: space_scoped_private_broker_creationDefault: 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_creationDefault: true Description: When enabled, space developers can create tasks. When disabled, only admin users can create tasks. |
Name: unset_roles_by_usernameDefault: 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_creationDefault: 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. |
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.
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 |
|---|---|---|
| name | string | Name of the isolation segment. |
| guid | uuid | Unique identifier for the isolation segment. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | labels object | Labels on the isolation segment |
| metadata.annotations (experimental) | annotations object | Annotations on the isolation segment |
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 (experimental) | label object | Labels applied to the isolation segment. |
| metadata.annotations (experimental) | 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": {}
}
}
Definition
GET /v3/isolation_segments/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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 an org manager, this is the isolation segments in the allowed list for any organization to which the user belongs. For any other user, this is the isolation segments assigned to any spaces to which the user has access.
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 | Experimental - A query string containing a list of label selector requirements. |
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
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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 (experimental) | label object | Labels applied to the isolation segment. |
| metadata.annotations (experimental) | 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": []
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the job. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | 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, COMPLETE, orFAILED. |
| links | links object | Links to related resources. |
| errors | errors list | Array of errors that occurred while processing the job. |
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": []
}
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"
}
]
}
Definition
GET /v3/jobs/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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. |
| 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 (experimental) | to-one relationship | The quota applied to the organization. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the organization. |
| metadata.annotations (experimental) | annotation object | Annotations added to the organization. |
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 (experimental) | boolean | Whether an organization is suspended or not. |
| metadata.labels (experimental) | label object | Labels applied to the organization. |
| metadata.annotations (experimental) | 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 | Experimental - A query string containing a list of label selector requirements. |
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 (experimental) | boolean | Whether an organization is suspended or not. |
| metadata.labels (experimental) | label object | Labels applied to the organization. |
| metadata.annotations (experimental) | 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,
"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
| Roles | Notes |
|---|---|
| Space Developer | |
| Space Manager | |
| Space Auditor | |
| Org Auditor | |
| Org Manager | |
| Org Billing Manager | Can only view domains without an organization relationship. |
| Admin | |
| Admin Read-Only | |
| Global Auditor |
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
},
"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 |
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 |
|---|---|---|
| type | string | Package type. Valid values are bits, docker. |
| data | object | Data for package type. |
| state | string | State of the package. Valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, EXPIRED. |
| guid | uuid | Unique identifier for the package. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| relationships.app (experimental) | to-one relationship | The app the package belongs to. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the package. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the package. |
Bits package
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 |
|---|---|---|
| type | string | bits |
| 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. |
| state | string | State of the package. Valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, EXPIRED. |
| guid | uuid | Unique identifier for the package. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the package. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the package. |
Docker package
A Docker package references a Docker image from a registry.
| Name | Type | Description |
|---|---|---|
| type | string | docker |
| 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. |
| state | string | State of the package. Valid states are READY, FAILED, COPYING, EXPIRED. |
| guid | uuid | Unique identifier for the package. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the package. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the package. |
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": "AWAITING_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 (experimental) | label object | Labels applied to the package. |
| metadata.annotations (experimental) | 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 |
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 | Experimental - A query string containing a list of label selector requirements. |
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. |
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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": { "key": "value" },
"annotations": { "note": "detailed information" }
}
}
Definition
PATCH /v3/packages/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the package. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the 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
webprocess and all other process types are scaled to zero - Scale the
webprocess to zero if it is not required for your app - Unless otherwise specified, all routes will be mapped to the
webprocess 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,
"health_check": {
"type": "port",
"data": {
"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",
"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 |
|---|---|---|
| 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. |
| disk_in_mb | integer | The disk in MB allocated per instance. |
| health_check | health check object | The health check to perform on the process. |
| relationships.app (experimental) | to-one relationship | The app the process belongs to. |
| relationships.revision (experimental) | to-one relationship | The app revision the process is currently running. |
| guid | uuid | Unique identifier for the process. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the process. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the process. |
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.endpoint | string | The endpoint called to determine if the app is healthy. This key is only present for http health checks. |
The process stats object
Example process stats object
{
"type": "web",
"index": 0,
"state": "RUNNING",
"usage": {
"time": "2016-03-23T23:17:30.476314154Z",
"cpu": 0.00038711029163348665,
"mem": 19177472,
"disk": 69705728
},
"host": "10.244.16.10",
"instance_ports": [
{
"external": 64546,
"internal": 8080
}
],
"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. |
| usage.time | datetime | 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. |
| host | string | The host the instance is running on. |
| 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 maximum memory the instance is allowed to use. |
| disk_quota | integer | The maximum disk the instance is allowed to use. |
| 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,
"health_check": {
"type": "port",
"data": {
"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",
"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
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
Get stats for 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,
"mem": 19177472,
"disk": 69705728
},
"host": "10.244.16.10",
"instance_ports": [
{
"external": 64546,
"internal": 8080
}
],
"uptime": 9042,
"mem_quota": 268435456,
"disk_quota": 1073741824,
"fds_quota": 16384,
"isolation_segment": "example_iso_segment",
"details": null
}
]
}
Definition
GET /v3/processes/:guid/stats
GET /v3/apps/:guid/processes/:type/stats
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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,
"health_check": {
"type": "port",
"data": {
"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",
"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,
"health_check": {
"type": "process",
"data": {
"timeout": null
}
},
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
},
"revision": null
},
"metadata": {
"labels": {},
"annotations": {}
},
"created_at": "2016-03-23T18:48:22Z",
"updated_at": "2016-03-23T18:48:42Z",
"links": {
"self": {
"href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
},
"scale": {
"href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/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/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
}
}
}
]
}
Retrieve all processes the user has access to.
Definition
GET /v3/processes
Query parameters
| Name | Type | Description |
|---|---|---|
| guids | list of strings | Comma-delimited list of process guids to filter by. |
| types | list of strings | Comma-delimited list of process 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 | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| All Roles |
List processes for app
Example Request
curl "https://api.example.org/v3/apps/[guid]/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/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/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,
"health_check": {
"type": "port",
"data": {
"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",
"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,
"health_check": {
"type": "process",
"data": {
"timeout": null
}
},
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
},
"revision": null
},
"metadata": {
"labels": {},
"annotations": {}
},
"created_at": "2016-03-23T18:48:22Z",
"updated_at": "2016-03-23T18:48:42Z",
"links": {
"self": {
"href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
},
"scale": {
"href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/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/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
}
}
}
]
}
Retrieves all processes belonging to an app.
Definition
GET /v3/apps/:guid/processes
Query parameters
| Name | Type | Description |
|---|---|---|
| guids | list of strings | Comma-delimited list of process guids to filter by. |
| types | list of strings | Comma-delimited list of process 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. |
| label_selector | string | Experimental - 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 |
Update a process
Example Request
curl "https://api.example.org/v3/processes/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"command": "rackup",
"metadata": {
"labels": {
"key": "value"
},
"annotations": {
"note": "detailed information"
}
}
}'
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,
"health_check": {
"type": "port",
"data": {
"timeout": null
}
},
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
},
"revision": {
"data": {
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
}
}
},
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information" }
},
"created_at": "2016-03-23T18:48:22Z",
"updated_at": "2016-03-23T18:48:42Z",
"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
PATCH /v3/processes/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| command | string or null | The command used to start the process. Use null to revert to the buildpack-detected or procfile-provided start command. |
| health_check | health check object | The health check to perform on the process. |
| metadata.labels (experimental) | label object | Labels applied to the process. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the process. |
Permitted roles
| Admin |
| Space Developer |
Scale a process
Example Request
curl "https://api.example.org/v3/processes/[guid]/actions/scale" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024
}'
Example Response
HTTP/1.1 202 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,
"health_check": {
"type": "port",
"data": {
"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",
"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
POST /v3/processes/:guid/actions/scale
POST /v3/apps/:guid/processes/:type/actions/scale
Optional parameters
| Name | Type | Description |
|---|---|---|
| instances | integer | The number of instances to run. |
| memory_in_mb | integer | The memory in mb allocated per instance. |
| disk_in_mb | integer | The disk in mb allocated per instance. |
Permitted roles
| Admin |
| Space Developer |
Terminate a process instance
Example Request
curl "https://api.example.org/v3/processes/[guid]/instances/[index]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
Terminate an instance of a specific process. Health management will eventually restart the instance.
This allows a user to stop a single misbehaving instance of a process.
Definition
DELETE /v3/processes/:guid/instances/:index
DELETE /v3/apps/:guid/processes/:type/instances/:index
Permitted Roles
| Admin |
| Space Developer |
Resource Matches
This endpoint matches given resource SHA-1/file size pairs against the Cloud Controller cache
and reports the subset that describes already cached files.
This is usually used to avoid uploading duplicate files
when pushing an app which has only been partially changed.
The path and mode fields are not used when matching.
When uploading package bits,
the response from this endpoint should be used as the resources form field.
As such, it is useful to include the path and mode fields for each resource
even though they are not used when determining a resource match.
Cloud Foundry operators may set minimum/maximum file sizes to match against. If the file size provided is outside this range, it will not be matched against.
If the resource_matching feature flag is disabled,
resource matching will always return an empty array.
The resource match object
Example Resource Match object
{
"resources": [
{
"checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
"size_in_bytes": 1,
"path": "path/to/file",
"mode": "644"
}
]
}
| Name | Type | Description |
|---|---|---|
| checksum.value | string | (Required) SHA-1 hash of file |
| size_in_bytes | integer | (Required) Size of file in bytes |
| path | string | Path to the file, relative to app root |
| mode | string | File mode, i.e. POSIX file permissions. Defaults to 0744 |
Create a resource match
Example Request
curl "https://api.example.org/v3/resource_matches" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{
"resources": [
{
"checksum": { "value": "002d760bea1be268e27077412e11a320d0f164d3" },
"size_in_bytes": 36,
"path": "C:\\path\\to\\file",
"mode": "645"
},
{
"checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
"size_in_bytes": 1,
"path": "path/to/file",
"mode": "644"
}
]
}'
Example Response
HTTP/1.1 201 OK
Content-Type: application/json
{
"resources": [
{
"checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
"size_in_bytes": 1,
"path": "path/to/file",
"mode": "644"
}
]
}
This endpoint returns a list of cached resources from the input list.
Definition
POST /v3/resource_matches
Required parameters
| Name | Type | Description |
|---|---|---|
| resources | array of resource_object | List of resources to check for in the resource cache |
Permitted roles
| All Roles |
Roles
Roles control access to resources in organizations and spaces. Roles are assigned to users.
For example, a user with the space_developer role is able to push
applications to their space. A space_manager user can also add roles to users
within that space (e.g. making a user a space_auditor). An
organization_manager has wide-reaching privileges, able to create & delete
spaces, and assign & unassign roles to users.
The role object
Example Role object
{
"guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
"created_at": "2019-10-10T17:19:12Z",
"updated_at": "2019-10-10T17:19:12Z",
"type": "organization_auditor",
"relationships": {
"user": {
"data": {
"guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
}
},
"organization": {
"data": {
"guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
},
"space": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
},
"user": {
"href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
},
"organization": {
"href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the role. |
| created_at | datetime | The time with zone when the role was created. |
| updated_at | datetime | The time with zone when the role was last updated. |
| type | string | Role type. See Valid role types. |
| relationships.user | to-one relationship | A relationship to the user. This is the user that has the role. |
| relationships.space | to-one relationship | A relationship to the space the role controls access to. When this is an organization role, space.data will be null. |
| relationships.organization | to-one relationship | A relationship to the organization the role controls access to. When this is a space role, organization.data will be null. |
| links | links object | Links to related resources. |
Valid role types
organization_userorganization_auditororganization_managerorganization_billing_managerspace_auditorspace_developerspace_manager
Create a role
Example Request (by user guid)
curl "https://api.example.org/v3/roles" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"type": "organization_auditor",
"relationships": {
"user": {
"data": {
"guid": "user-guid"
}
},
"organization": {
"data": {
"guid": "org-guid"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
"created_at": "2019-10-10T17:19:12Z",
"updated_at": "2019-10-10T17:19:12Z",
"type": "organization_auditor",
"relationships": {
"user": {
"data": {
"guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
}
},
"organization": {
"data": {
"guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
},
"space": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
},
"user": {
"href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
},
"organization": {
"href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
}
}
Example Request (by username and origin)
curl "https://api.example.org/v3/roles" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"type": "organization_auditor",
"relationships": {
"user": {
"data": {
"username": "user-name",
"origin": "ldap"
}
},
"organization": {
"data": {
"guid": "org-guid"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
"created_at": "2019-10-10T17:19:12Z",
"updated_at": "2019-10-10T17:19:12Z",
"type": "organization_auditor",
"relationships": {
"user": {
"data": {
"guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
}
},
"organization": {
"data": {
"guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
},
"space": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
},
"user": {
"href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
},
"organization": {
"href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
}
}
This endpoint creates a new role for a user in an organization or space.
To create an organization role you must be an admin or organization manager in the organization associated with the role.
To create a space role you must be an admin, an organization manager in the parent organization of the space associated with the role, or a space manager in the space associated with the role.
For a user to be assigned a space role, the user must already have an organization role in the parent organization.
If the associated user is valid but does not exist in Cloud Controller’s database, a user resource will be created automatically.
Definition
POST /v3/roles
Required parameters
| Name | Type | Description |
|---|---|---|
| type | string | Role to create. See valid role types. |
| relationships.user | to-one relationship | A relationship to a user. The user can be defined by either a guid or, if the set_roles_by_username feature_flag is enabled, a username (with the option of including an origin to disambiguate it). |
| relationships.organization | to-one relationship | A relationship to an organization. Required only when creating an organization role. |
| relationships.space | to-one relationship | A relationship to a space. Required only when creating a space role. |
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Org Manager | Can create roles in managed organizations and spaces within those organizations. Can also create roles for users outside of managed organizations when set_roles_by_username feature_flag is enabled. This requires identifying users by username and origin. |
| Space Manager | Can create roles in managed spaces for users in their org. |
Get a role
Example Request
curl "https://api.example.org/v3/roles/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
"created_at": "2019-10-10T17:19:12Z",
"updated_at": "2019-10-10T17:19:12Z",
"type": "organization_auditor",
"relationships": {
"user": {
"data": {
"guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
}
},
"organization": {
"data": {
"guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
},
"space": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
},
"user": {
"href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
},
"organization": {
"href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
}
}
This endpoint gets an individual role resource.
Definition
GET /v3/roles/:guid
Query parameters
| Name | Type | Description |
|---|---|---|
| include | list of strings | Experimental - Optionally include a list of unique related resources in the response. Valid values are user, space, and organization. |
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Admin Read-Only | |
| Global Auditor | |
| Org Manager | Can see roles in managed organizations or spaces in those organizations. |
| Org Auditor | Can only see organization roles in audited organizations. |
| Org Billing Manager | Can only see organization roles in billing-managed organizations. |
| Space Auditor | Can see roles in audited spaces or parent organizations. |
| Space Developer | Can see roles in developed spaces or parent organizations. |
| Space Manager | Can see roles in managed spaces or parent organizations. |
List roles
Example Request
curl "https://api.example.org/v3/roles" \
-X GET \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json"
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"pagination": {
"total_results": 3,
"total_pages": 2,
"first": {
"href": "https://api.example.org/v3/roles?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/roles?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/roles?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
"created_at": "2019-10-10T17:19:12Z",
"updated_at": "2019-10-10T17:19:12Z",
"type": "organization_auditor",
"relationships": {
"user": {
"data": {
"guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
}
},
"organization": {
"data": {
"guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
},
"space": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
},
"user": {
"href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
},
"organization": {
"href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
}
},
{
"guid": "12347c70-d1bd-4976-a2ab-a85f5e882418",
"created_at": "2047-11-10T17:19:12Z",
"updated_at": "2047-11-10T17:19:12Z",
"type": "space_auditor",
"relationships": {
"user": {
"data": {
"guid": "47eadb5f-fc13-414f-84ba-47a35e239cc8"
}
},
"organization": {
"data": null
},
"space": {
"data": {
"guid": "47c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/roles/12347c70-d1bd-4976-a2ab-a85f5e882418"
},
"user": {
"href": "https://api.example.org/v3/users/47eadb5f-fc13-414f-84ba-77a35e239cc8"
},
"space": {
"href": "https://api.example.org/v3/spaces/47c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
}
}
}
]
}
This endpoint lists roles that the user has access to.
Definition
GET /v3/roles
Query parameters
| Name | Type | Description |
|---|---|---|
| guids | list of strings | Comma-delimited list of role guids to filter by. |
| types | list of strings | Comma-delimited list of role types 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. |
| user_guids | list of strings | Comma-delimited list of user 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. |
| include | list of strings | Experimental - Optionally include a list of unique related resources in the response. Valid values are user, space, and organization. |
Permitted roles
| All Roles |
Delete a role
This endpoint deletes an individual role.
Example Request
curl "https://api.example.org/v3/roles/[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/roles/:guid
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Org Manager | Can delete roles in managed organizations or spaces in those organizations. |
| Space Manager | Can delete roles in managed spaces |
Routes
Routes are addresses that direct matched network traffic to one or more destinations. Each route is based on a domain name with additional matching criteria (host (subdomain), path, etc). Matched traffic will be distributed across all destinations, based on their configuration (round-robin by default).
The route object
Example Route object
{
"guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"destinations": [
{
"guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
"app": {
"guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
},
{
"guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
"app": {
"guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
}
],
"metadata": {
"labels": { },
"annotations": { }
},
"relationships": {
"space": {
"data": {
"guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
}
},
"domain": {
"data": {
"guid": "0b5f3633-194c-42d2-9408-972366617e0e"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
},
"space": {
"href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
},
"domain": {
"href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
},
"destinations": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the route. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| host | string | The hostname for the route. Must be under 63 character long and only contain letters, numbers, dashes (-) or underscores(_). |
| path | string | The path for the route. Must be under 128 character long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from RFC 2396. |
| url | string | The URL for the route. Combination of host, domain name, and path. |
| destinations | array of destination objects | List of destinations for the route. |
| space | to-one relationship | A relationship to the space containing the route. Routes can only be mapped to destinations in that space. |
| domain | to-one relationship | A relationship to the domain of the route. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the route. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the route. |
The destination object
Example Destination object
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"app": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
}
A destination represents the relationship between a route and a resource that can serve traffic (for example, the web process of an application).
When a route has destinations, that route will direct traffic to the processes represented by those destinations.
If a destination is created with a port specified, the route will direct traffic to that port on the process. A destination with port 9000 and process type api means traffic will be directed to the api process running on container port 9000.
Note that when using a custom port, the app process must be listening on the specified port for the mapping to work. Otherwise, visiting the route will result in a 404 error.
If a destination does not specify a port, the default port depends on the app lifecycle type. For buildpack apps, traffic will be directed to port 8080. For Docker apps, the first port specified in the Dockerfile will be used.
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the destination. |
| app.guid | uuid | Unique identifier for the app to route traffic to. |
| app.process.type | string | Type of the process belonging to the app to route traffic to. |
| port | integer | Port on the destination process to route traffic to. |
| weight (experimental) | integer or null |
Percentage of traffic which will be routed to this destination. This feature is only available via the BETA Service Mesh routing plane. |
Create a route
Example Request
curl "https://api.example.org/v3/routes" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"host": "a-hostname",
"path": "/some_path",
"relationships": {
"domain": {
"data": { "guid": "domain-guid" }
},
"space": {
"data": { "guid": "space-guid" }
}
},
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information"}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"destinations": [
{
"guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
"app": {
"guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
},
{
"guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
"app": {
"guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
}
],
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information" }
},
"relationships": {
"space": {
"data": {
"guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
}
},
"domain": {
"data": {
"guid": "0b5f3633-194c-42d2-9408-972366617e0e"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
},
"space": {
"href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
},
"domain": {
"href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
},
"destinations": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
}
}
}
Definition
POST /v3/routes
Required parameters
| Name | Type | Description |
|---|---|---|
| relationships.space | to-one relationship | A relationship to the space containing the route. Routes can only be mapped to destinations in that space. |
| relationships.domain | to-one relationship | A relationship to the domain of the route. |
Optional parameters
| Name | Type | Description |
|---|---|---|
| host | string | The host component for the route. |
| path | string | The path component for the route. Should begin with a /. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the route. |
| metadata.labels (experimental) | label object | Labels applied to the route. |
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Space Developer |
Get a route
Example Request
curl "https://api.example.org/v3/routes/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"destinations": [
{
"guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
"app": {
"guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
},
{
"guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
"app": {
"guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
}
],
"metadata": {
"labels": { },
"annotations": { }
},
"relationships": {
"space": {
"data": {
"guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
}
},
"domain": {
"data": {
"guid": "0b5f3633-194c-42d2-9408-972366617e0e"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
},
"space": {
"href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
},
"domain": {
"href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
},
"destinations": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
}
}
}
Definition
GET /v3/routes/:guid
Query parameters
| Name | Type | Description |
|---|---|---|
| include | string | Experimental - Optionally include additional related resources in the response. Valid value is domain |
Permitted roles
| Role | Notes |
|---|---|
| Admin Read-Only | |
| Admin | |
| Global Auditor | |
| Org Auditor | |
| Org Manager | |
| Space Auditor | |
| Space Developer | |
| Space Manager |
List routes
Example Request
curl "https://api.example.org/v3/routes" \
-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/routes?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/routes?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/routes?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"destinations": [
{
"guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
"app": {
"guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
},
{
"guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
"app": {
"guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
}
],
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"space": {
"data": {
"guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
}
},
"domain": {
"data": {
"guid": "0b5f3633-194c-42d2-9408-972366617e0e"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
},
"space": {
"href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
},
"domain": {
"href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
},
"destinations": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
}
}
}
]
}
Retrieve all routes the user has access to.
Definition
GET /v3/routes
Query parameters
| Name | Type | Description |
|---|---|---|
| hosts | list of strings | Comma-delimited list of hostnames to filter by. |
| paths | list of strings | Comma-delimited list of paths to filter by (e.g. /path1,/path2). |
| domain_guids | list of strings | Comma-delimited list of domain 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 | Experimental - A query string containing a list of label selector requirements. |
| include | string | Experimental - Optionally include a list of unique related resources in the response. Valid value is domain |
Permitted roles
| All Roles |
List routes for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/routes" \
-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/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"destinations": [
{
"guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
"app": {
"guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
},
{
"guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
"app": {
"guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
}
],
"metadata": {
"labels": {},
"annotations": {}
},
"relationships": {
"space": {
"data": {
"guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
}
},
"domain": {
"data": {
"guid": "0b5f3633-194c-42d2-9408-972366617e0e"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
},
"space": {
"href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
},
"domain": {
"href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
},
"destinations": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
}
}
}
]
}
Retrieve all routes that have destinations that point to the given app.
Definition
GET /v3/apps/:guid/routes
Query parameters
| Name | Type | Description |
|---|---|---|
| hosts | list of strings | Comma-delimited list of hostnames to filter by. |
| paths | list of strings | Comma-delimited list of paths to filter by (e.g. /path1,/path2). |
| domain_guids | list of strings | Comma-delimited list of domain 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 | Experimental - 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 |
Update a route
Example Request
curl "https://api.example.org/v3/routes/[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": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"destinations": [
{
"guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
"app": {
"guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
},
{
"guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
"app": {
"guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
}
],
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information" }
},
"relationships": {
"space": {
"data": {
"guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
}
},
"domain": {
"data": {
"guid": "0b5f3633-194c-42d2-9408-972366617e0e"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
},
"space": {
"href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
},
"domain": {
"href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
},
"destinations": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
}
}
}
Definition
PATCH /v3/routes/:guid
Optional parameters
| Name | Type | Description | Default |
|---|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the route. | |
| metadata.annotations (experimental) | annotation object | Annotations applied to the route. |
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Space Developer |
Delete a route
Example Request
curl "https://api.example.org/v3/routes/[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/routes/:guid
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Space Developer |
Check reserved routes for a domain
Example Request
curl "https://api.example.org/v3/domains/[guid]/route_reservations" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{ "matching_route": true }
Check if a specific route for a domain exists, regardless of the user’s visibility for the route in case the route belongs to a space the user does not belong to.
Definition
GET /v3/domains/:guid/route_reservations
Query parameters
| Name | Type | Description |
|---|---|---|
| host | string | Hostname to filter by. Defaults to empty string if not provided. |
| path | string | Path to filter by. Defaults to empty string if not provided. |
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Admin Read-Only | |
| Global Auditor | |
| Org Auditor | |
| Org Billing Manager | Can only check if routes exist for a domain without an organization relationship. |
| Org Manager | |
| Space Auditor | |
| Space Developer | |
| Space Manager |
List destinations for a route
Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"destinations": [
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"app": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
},
{
"guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
"app": {
"guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
"process": {
"type": "api"
}
},
"weight": null,
"port": 9000
}
],
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
},
"route": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
}
}
}
Retrieve all destinations associated with a route.
Definition
GET /v3/routes/:guid/destinations
Query parameters
| Name | Type | Description |
|---|---|---|
| guids | list of strings | Comma-delimited list of destination guids to filter by. |
| app_guids | list of strings | Comma-delimited list of app guids to filter by. |
Permitted roles
| Role | Notes |
|---|---|
| Admin Read-Only | |
| Admin | |
| Global Auditor | |
| Org Auditor | |
| Org Manager | |
| Space Auditor | |
| Space Developer | |
| Space Manager |
Insert destinations for a route
Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations" \
-X POST \
-H "Authorization: bearer [token]"
-d '{
"destinations": [
{
"app": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
},
{
"app": {
"guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
"process": {
"type": "api"
}
},
"port": 9000
}
]
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"destinations": [
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"app": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"process": {
"type": "web"
}
},
"weight": null,
"port": 8080
},
{
"guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
"app": {
"guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
"process": {
"type": "api"
}
},
"weight": null,
"port": 9000
}
],
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
},
"route": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
}
}
}
Add one or more destinations to a route, preserving any existing destinations.
Note that weighted destinations cannot be added with this endpoint. To add weighted destinations, replace all destinations for a route at once using the replace destinations endpoint.
Definition
POST /v3/routes/:guid/destinations
Required parameters
| Name | Type | Description |
|---|---|---|
| destinations | array of destination objects | List of destinations to add to route. Destinations without process.type specified will get process type "web" by default. |
Permitted roles
| Role |
|---|
| Admin |
| Space Developer |
Replace all destinations for a route
Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations" \
-X PATCH \
-H "Authorization: bearer [token]"
-d '{
"destinations": [
{
"app": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"weight": 61
},
{
"app": {
"guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
"process": {
"type": "api"
}
},
"weight": 39,
"port": 9000
}
]
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"destinations": [
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"app": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"process": {
"type": "web"
}
},
"weight": 61,
"port": 8080
},
{
"guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
"app": {
"guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
"process": {
"type": "api"
}
},
"weight": 39,
"port": 9000
}
],
"links": {
"self": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
},
"route": {
"href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
}
}
}
Replaces all destinations for a route, removing any destinations not included in the provided list.
If using weighted destinations, all destinations provided here must have a weight specified, and all weights
for this route must sum to 100. If not, all provided destinations must not have a weight. Mixing weighted
and unweighted destinations for a route is not allowed.
Definition
PATCH /v3/routes/:guid/destinations
Required parameters
| Name | Type | Description |
|---|---|---|
| destinations | array of destination objects | List of destinations use for route. Destinations without process.type specified will get process type "web" by default. |
Permitted roles
| Role |
|---|
| Admin |
| Space Developer |
Remove destination for a route
Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations/[destination_guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
Remove a destination from a route.
Definition
DELETE /v3/routes/:guid/destinations/:destination_guid
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Space Developer |
Delete unmapped routes for a space
Example Request
curl "https://api.example.org/v3/spaces/[guid]/routes?unmapped=true" \
-X DELETE\
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]
Deletes all routes in a space that are not mapped to any applications and not bound to any service instances.
Definition
DELETE /v3/spaces/:guid/routes?unmapped=true
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Space Developer |
Note: unmapped=true is a required query parameter; always include it.
Service Instances
An instantiation of a service offering.
The service instance object
Example Service Instance object
{
"guid": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
"created_at": "2017-11-17T13:54:21Z",
"updated_at": "2017-11-17T13:54:21Z",
"name": "my_service_instance",
"relationships": {
"space": {
"data": {
"guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
}
}
},
"metadata": {
"labels": { },
"annotations": { }
},
"links": {
"space": {
"href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
}
}
}
| Name | Type | Description |
|---|---|---|
| name | string | Name of the service instance. |
| guid | uuid | Unique identifier for the service instance. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| relationships.space | to-one relationship | The space the service instance is contained in. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the service instance. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the service instance. |
List service instances
Example Request
curl "https://api.example.org/v3/service_instances" \
-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/service_instances?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/service_instances?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
"created_at": "2017-11-17T13:54:21Z",
"updated_at": "2017-11-17T13:54:21Z",
"name": "my_service_instance",
"relationships": {
"space": {
"data": {
"guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
}
}
},
"metadata": {
"labels": { },
"annotations": { }
},
"links": {
"space": {
"href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
}
}
}
]
}
This endpoint retrieves the service instances the user has access to. At the moment, this endpoint only returns managed service instances. This may change in the future.
This includes access granted by service instance sharing.
Definition
GET /v3/service_instances
Query parameters
| Name | Type | Description |
|---|---|---|
| names | list of strings | Comma-delimited list of service instance names to filter by. |
| space_guids | list of strings | Comma-delimited list of space 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. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| All Roles |
List shared spaces relationship
Example Request
curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces" \
-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/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
}
}
}
This endpoint lists the spaces that the service instance has been shared to.
Definition
GET /v3/service_instances/:guid/relationships/shared_spaces
Permitted roles (in the service instance’s originating space)
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
Update a service instance
Example Request
curl "https://api.example.org/v3/service_instances/[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": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
"created_at": "2017-11-17T13:54:21Z",
"updated_at": "2017-11-17T13:54:21Z",
"name": "my_service_instance",
"relationships": {
"space": {
"data": {
"guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
}
}
},
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information" }
},
"links": {
"space": {
"href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
}
}
}
Definition
PATCH /v3/service_instances/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the service_instance. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the service_instance. |
Permitted roles
| Admin |
| Space Developer |
Share a service instance to other spaces
Example Request
curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"data": [
{ "guid":"space-guid-1" },
{ "guid":"space-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/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
}
}
}
This endpoint shares the service instance with the specified spaces. In order to share into a space the requesting user must be a space developer in the target space.
Definition
POST /v3/service_instances/:guid/relationships/shared_spaces
Required parameters
| Name | Type | Description |
|---|---|---|
| data | to-many relationship | Shared space relationships. Each space will have this service instance shared to it. |
Permitted roles
| Admin |
| Space Developer |
Unshare a service instance from another space
Example Request
curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces/[space_guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
This endpoint unshares the service instance with the specified space. This will automatically unbind any applications bound to this service instance in the specified space.
Definition
DELETE /v3/service_instances/:guid/relationships/shared_spaces/:space_guid
Permitted roles
| Admin |
| Space Developer |
Spaces
Every application and service is scoped to a space. Each org contains at least one space. A space provides users with access to a shared location for application development, deployment, and maintenance.
The space object
Example Space object
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "my-space",
"relationships": {
"organization": {
"data": {
"guid": "e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"quota": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"organization": {
"href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the space. |
| name | string | Name of the space. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| relationships.organization | to-one relationship | The organization the space is contained in. |
| relationships.quota (experimental) | to-one relationship | The space quota applied to the space. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the space. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the space. |
Create a space
Example Request
curl "https://api.example.org/v3/spaces" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{
"name": "my-space",
"relationships": {
"organization": {
"data": {
"guid": "[org-guid]"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "my-space",
"relationships": {
"organization": {
"data": {
"guid": "e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"quota": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"organization": {
"href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
POST /v3/spaces
Required parameters
| Name | Type | Description |
|---|---|---|
| name | string | Space name |
| relationships.organization | to-one relationship | A relationship to an organization. |
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the space. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the space. |
Permitted roles
| Admin |
| Org Manager |
Get a space
Example Request
curl "https://api.example.org/v3/spaces/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "my-space",
"relationships": {
"organization": {
"data": {
"guid": "e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"quota": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"organization": {
"href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
This endpoint retrieves the specified space object.
Definition
GET /v3/spaces/:guid
Query parameters
| Name | Type | Description |
|---|---|---|
| include | string | Experimental - Optionally include additional related resources in the response. Valid value is organization. |
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
List spaces
Example Request
curl "https://api.example.org/v3/spaces" \
-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/spaces?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/spaces?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": "space1",
"relationships": {
"organization": {
"data": {
"guid": "e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"quota": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"organization": {
"href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
"created_at": "2017-02-02T00:14:30Z",
"updated_at": "2017-02-02T00:14:30Z",
"name": "space2",
"relationships": {
"organization": {
"data": {
"guid": "b4ce91bd-31df-4b7d-8fd4-21a6b533276b"
}
},
"quota": {
"data": {
"guid": "6da62599-4890-4a08-8b6f-180a4f47e46b"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
},
"organization": {
"href": "https://api.example.org/v3/organizations/b4ce91bd-31df-4b7d-8fd4-21a6b533276b"
},
"quota": {
"href": "https://api.example.org/v3/space_quotas/6da62599-4890-4a08-8b6f-180a4f47e46b"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
Retrieve all spaces the user has access to.
Definition
GET /v3/spaces
Query parameters
| Name | Type | Description |
|---|---|---|
| names | list of strings | Comma-delimited list of space names to filter by. |
| 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, name. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
| include | string | Experimental - Optionally include a list of unique related resources in the response. Valid value is organization. |
Permitted roles
| All Roles |
Update a space
Example Request
curl "https://api.example.space/v3/spaces/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{ "name": "new-space-name" }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"name": "my-space",
"relationships": {
"organization": {
"data": {
"guid": "e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"quota": {
"data": null
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"organization": {
"href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
PATCH /v3/spaces/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| name | string | New space name |
| metadata.labels (experimental) | label object | Labels applied to the space. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the space. |
Permitted roles
| Admin |
| Org Manager |
| Space Manager |
Delete a space
When a space is deleted, the user roles associated with the space will be deleted.
Example Request
curl "https://api.example.org/v3/spaces/[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/spaces/:guid
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Org Manager |
Get assigned isolation segment
Example Request
curl "https://api.example.org/v3/spaces/[guid]/relationships/isolation_segment" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
},
"links": {
"self": {
"href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment"
},
"related": {
"href": "https://api.example.org/v3/isolation_segments/e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
}
}
}
Definition
GET /v3/spaces/:guid/relationships/isolation_segment
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
Manage isolation segment
Example Request
curl "https://api.example.org/v3/spaces/[guid]/relationships/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": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
},
"links": {
"self": {
"href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment"
},
"related": {
"href": "https://api.example.org/v3/isolation_segments/e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
}
}
}
This endpoint assigns an isolation segment to the space. The isolation segment must be entitled to the space’s parent organization.
Definition
PATCH /v3/spaces/:guid/relationships/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 |
Stacks
Stacks are the base operating system and file system that your application will execute in. A stack is how you configure applications to run against different operating systems (like Windows or Linux) and different versions of those operating systems (like Windows 2012 or Windows 2016).
An application’s lifecycle will specify which stack to execute the application in. Buildpacks can also be associated with a particular stack if they contain stack-specific logic. An application will automatically use buildpacks associated with the application’s configured stack.
Stacks are not used for apps with a Docker lifecycle.
The stack object
Example Stack object
{
"guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
"created_at": "2018-11-09T22:43:28Z",
"updated_at": "2018-11-09T22:43:28Z",
"name": "my-stack",
"description": "Here is my stack!",
"metadata": {
"labels": { },
"annotations": { }
},
"links": {
"self": {
"href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
}
}
}
| Name | Type | Description |
|---|---|---|
| name | string | The name of the stack |
| description | string | The description of the stack |
| guid | uuid | Unique identifier for the stack. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| metadata.labels (experimental) | label object | Labels applied to the stack. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the stack. |
| links | links object | Links to related resources. |
Create a stack
Example Request
curl "https://api.example.org/v3/stacks" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "my-stack",
"description": "Here is my stack!",
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
"created_at": "2018-11-09T22:43:28Z",
"updated_at": "2018-11-09T22:43:28Z",
"name": "my-stack",
"description": "Here is my stack!",
"metadata": {
"labels": { },
"annotations": { }
},
"links": {
"self": {
"href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
}
}
}
Definition
POST /v3/stacks
Required parameters
| Name | Type | Description |
|---|---|---|
| name | string | Name of the stack. Must be unique and no longer than 250 characters. |
Optional parameters
| Name | Type | Description | Default |
|---|---|---|---|
| description | string | Description of the stack. Must no longer than 250 characters. | null |
| metadata.labels (experimental) | label object | Labels applied to the stack. | |
| metadata.annotations (experimental) | annotation object | Annotations applied to the stack. |
Permitted roles
| Admin |
Get a stack
Example Request
curl "https://api.example.org/v3/stacks/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
"created_at": "2018-11-09T22:43:28Z",
"updated_at": "2018-11-09T22:43:28Z",
"name": "my-stack",
"description": "Here is my stack!",
"metadata": {
"labels": { },
"annotations": { }
},
"links": {
"self": {
"href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
}
}
}
Definition
GET /v3/stacks/:guid
Permitted roles
| All Roles |
List stacks
Example Request
curl "https://api.example.org/v3/stacks" \
-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/stacks?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/stacks?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/stacks?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
"created_at": "2018-11-09T22:43:28Z",
"updated_at": "2018-11-09T22:43:28Z",
"name": "my-stack-1",
"description": "This is my first stack!",
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
}
}
},
{
"guid": "81c916c9-c2f9-440e-8e73-102e79c4704h",
"created_at": "2018-11-09T22:43:29Z",
"updated_at": "2018-11-09T22:43:29Z",
"name": "my-stack-2",
"description": "This is my second stack!",
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/stacks/81c916c9-c2f9-440e-8e73-102e79c4704h"
}
}
}
]
}
Retrieve all stacks.
Definition
GET /v3/stacks
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 app names to filter by. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| All Roles |
Update a stack
Example Request
curl "https://api.example.org/v3/stacks/[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": "11c916c9-c2f9-440e-8e73-102e79c4704d",
"created_at": "2018-11-09T22:43:28Z",
"updated_at": "2018-11-09T22:43:28Z",
"name": "my-stack",
"description": "Here is my stack!",
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information" }
},
"links": {
"self": {
"href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
}
}
}
Definition
PATCH /v3/stacks/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the stack. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the stack. |
Permitted roles
| Admin |
| Space Developer |
Delete a stack
Example Request
curl "https://api.example.org/v3/stacks/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
Definition
DELETE /v3/stacks/:guid
Permitted roles
| Admin |
Tasks
Tasks are one-off jobs that are intended to perform a task, stop, and be cleaned up, freeing up resources.
Examples of this include database migrations, sending things, and batch jobs.
The task object
Example Task object
{
"guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
"sequence_id": 1,
"name": "migrate",
"command": "rake db:migrate",
"state": "RUNNING",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": null
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { },
"annotations": { }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
| Name | Type | Description |
|---|---|---|
| sequence_id | integer | User-facing id of the task. This number is unique for every task associated with a given app. |
| name | string | Name of the task. |
| command | string | Command that will be executed. This field may be excluded based on a user’s role. |
| disk_in_mb | integer | Amount of disk to allocate for the task in MB. |
| memory_in_mb | integer | Amount of memory to allocate for the task in MB. |
| state | string | State of the task. Possible states are PENDING, RUNNING, SUCCEEDED, CANCELING, and FAILED |
| droplet_guid | uuid | The guid of the droplet that will be used to run the command. |
| result | object | Results from the task |
| result.failure_reason | string | Null if the task succeeds, contains the error message if it fails. |
| guid | uuid | Unique identifier for the task. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| relationships.app | datetime | The app the task belongs to. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the task. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the task. |
Create a task
Example Request with Command
curl "https://api.example.org/v3/apps/[guid]/tasks" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{ "command": "rake db:migrate" }'
Example Request with Template Process
curl "https://api.example.org/v3/apps/[guid]/tasks" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{ "template": { "process": {"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e"} } }'
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
"sequence_id": 1,
"name": "migrate",
"command": "rake db:migrate",
"state": "RUNNING",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": null
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { },
"annotations": { }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
Definition
POST /v3/apps/:guid/tasks
Required parameters
| Name | Type | Description |
|---|---|---|
| command[1] | string | Command that will be executed. NOTE: optional if a template.process.guid is provided |
Optional parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | string | Name of the task. | auto-generated |
| disk_in_mb[1] | integer | Amount of disk to allocate for the task in MB. | operator-configured default_app_disk_in_mb |
| memory_in_mb[1] | integer | Amount of memory to allocate for the task in MB. | operator-configured default_app_memory |
| droplet_guid | uuid | The guid of the droplet that will be used to run the command. | the app’s current droplet |
| template.process.guid (experimental) | uuid | The guid of the process that will be used as a template. | null |
| metadata.labels (experimental) | label object | Labels applied to the package. | |
| metadata.annotations (experimental) | annotation object | Annotations applied to the package. |
1 If not provided, and a template.process.guid is provided, this field will use the value from the process with the given guid.
Permitted roles
| Admin |
| Space Developer |
Get a task
Example Request
curl "https://api.example.org/v3/tasks/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
"sequence_id": 1,
"name": "migrate",
"command": "rake db:migrate",
"state": "RUNNING",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": null
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { },
"annotations": { }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
Retrieve a specific task. The command field may be excluded
in the response based on the user’s role.
Definition
GET /v3/tasks/:guid
Permitted roles
| Admin Read-Only |
| Admin |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
List tasks
Example Request
curl "https://api.example.org/v3/tasks" \
-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/tasks?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/tasks?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/tasks?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
"sequence_id": 1,
"name": "hello",
"state": "SUCCEEDED",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": null
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { },
"annotations": { }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
},
{
"guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
"sequence_id": 2,
"name": "migrate",
"state": "FAILED",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": "Exited with status 1"
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { },
"annotations": { }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
]
}
Retrieve all tasks the user has access to. The command field is excluded in the response.
Definition
GET /v3/tasks
Query parameters
| Name | Type | Description |
|---|---|---|
| guids | list of strings | Comma-delimited list of task guids to filter by. |
| names | list of strings | Comma-delimited list of task names to filter by. |
| states | list of strings | Comma-delimited list of task 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, updated_at. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| All Roles |
List tasks for an app
Example Request
curl "https://api.example.org/v3/apps/:guid/tasks" \
-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/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
"sequence_id": 1,
"name": "hello",
"state": "SUCCEEDED",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": null
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { },
"annotations": { }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
},
{
"guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
"sequence_id": 2,
"name": "migrate",
"state": "FAILED",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": "Exited with status 1"
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { },
"annotations": { }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
]
}
Retrieve tasks for an app the user has access to. The command field may be
excluded in the response based on the user’s role.
Definition
GET /v3/apps/:guid/tasks
Query parameters
| Name | Type | Description |
|---|---|---|
| guids | list of strings | Comma-delimited list of task guids to filter by. |
| names | list of strings | Comma-delimited list of task names to filter by. |
| states | list of strings | Comma-delimited list of task states to filter by. |
| sequence_ids | list of strings | Comma delimited list of sequence ids to filter by. Valid values are integers >= 1 |
| 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 | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| Admin Read-Only |
| Admin |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
Update a task
Example Request
curl "https://api.example.org/v3/tasks/[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": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
"sequence_id": 1,
"name": "migrate",
"command": "rake db:migrate",
"state": "RUNNING",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": null
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information" }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
Definition
PATCH /v3/tasks/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the task. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the task. |
Permitted roles
| Admin |
| Space Developer |
Cancel a task
Example Request
curl "https://api.example.org/v3/tasks/[guid]/actions/cancel" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
"sequence_id": 1,
"name": "migrate",
"command": "rake db:migrate",
"state": "CANCELING",
"memory_in_mb": 512,
"disk_in_mb": 1024,
"result": {
"failure_reason": null
},
"droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
"metadata": {
"labels": { },
"annotations": { }
},
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"relationships": {
"app": {
"data": {
"guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"cancel": {
"href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
"method": "POST"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
Cancels a running task.
Canceled tasks will initially be in state CANCELING and will move to state FAILED once the cancel request has been processed.
Cancel requests are idempotent and will be processed according to the state of the task when the request is executed.
Canceling a task that is in SUCCEEDED or FAILED state will return an error.
Definition
POST /v3/tasks/:guid/actions/cancel
PUT /v3/tasks/:guid/cancel (Deprecated)
Permitted roles
| Admin |
| Space Developer |
Users
Every Cloud Foundry action (pushing an application, creating a space) requires a user. Each Cloud Foundry installation has one pre-installed user, admin, which can create subsequent users. Users can be assigned roles which give them privileges to perform actions. For example, the Space Developer role grants a user permission to manage apps and services in a space (to push apps, scale apps, delete apps).
The user object
Example User object
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"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/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the user. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| username | string | The name registered in UAA. Will be null for UAA clients and non-UAA users. |
| presentation_name | string | The name displayed for the user. For UAA users, this is the same as the username. For UAA clients, this is the UAA client ID. |
| origin | string | The identity provider for the UAA user. Will be null for UAA clients. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the user. |
| metadata.annotations (experimental) | annotation object | Annotations added to the user. |
Create a user
Creating a user requires one value, a GUID. This creates a user in the Cloud Controller database.
Generally, the GUID should match the GUID of an already-created user in the UAA database, though this is not required.
Example Request
curl "https://api.example.org/v3/users" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
}'
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",
"username": "some-name",
"presentation_name": "some-name",
"origin": "uaa",
"metadata": {
"labels": {},
"annotations":{}
},
"links": {
"self": {
"href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
}
}
}
Definition
POST /v3/users
Required parameters
| Name | Type | Description |
|---|---|---|
| guid | string | Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user’s GUID. In the case of UAA clients, this will match the UAA client ID. |
| metadata.labels (experimental) | label object | Labels applied to the user. |
| metadata.annotations (experimental) | annotation object | Annotations added to the user. |
Permitted roles
| Role | Notes |
|---|---|
| Admin |
Get a user
Example Request
curl "https://api.example.org/v3/users/[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",
"username": "some-name",
"presentation_name": "some-name",
"origin": "uaa",
"metadata": {
"labels": {},
"annotations":{}
},
"links": {
"self": {
"href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
}
}
}
Definition
GET /v3/users/:guid
Permitted roles
| Roles | Notes |
|---|---|
| Admin Read-Only | |
| Admin | |
| Global Auditor | |
| Org Auditor | Can only view users affiliated with their org |
| Org Billing Manager | Can only view users affiliated with their org |
| Org Manager | Can only view users affiliated with their org |
| Space Auditor | Can only view users affiliated with their org |
| Space Developer | Can only view users affiliated with their org |
| Space Manager | Can only view users affiliated with their org |
Note: A user can always see themselves with this endpoint, regardless of role.
List users
Example Request
curl "https://api.example.org/v3/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/users?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/users?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/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 that the current user can see.
Definition
GET /v3/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. |
| 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. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| Roles | Notes |
|---|---|
| Admin Read-Only | |
| Admin | |
| Global Auditor | |
| Org Auditor | Can only view users affiliated with their org |
| Org Billing Manager | Can only view users affiliated with their org |
| Org Manager | Can only view users affiliated with their org |
| Space Auditor | Can only view users affiliated with their org |
| Space Developer | Can only view users affiliated with their org |
| Space Manager | Can only view users affiliated with their org |
Update a user
Update a user’s metadata.
Example Request
curl "https://api.example.org/v3/users/24d59a1e-2613-4255-86a2-e0454cc6e261" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"metadata": {
"labels": { "enviroment": "production" },
"annotations": { "note": "detailed information" }
}'
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",
"username": "some-name",
"presentation_name": "some-name",
"origin": "uaa",
"metadata": {
"labels": { "enviroment": "production" },
"annotations": { "note": "detailed information" }
},
"links": {
"self": {
"href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
}
}
}
Definition
PATCH /v3/users
Required parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the app. |
| metadata.annotations (experimental) | annotation object | Annotations added to the user. |
Permitted roles
| Admin |
Delete a user
All roles associated with a user will be deleted if the user is deleted.
Example Request
curl "https://api.example.org/v3/users/[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/users/:guid
Permitted roles
| Role | Notes |
|---|---|
| Admin |
Experimental Resources
App Manifest
The app manifest is a method for applying bulk configuration to an app and its underlying processes.
The app manifest specification
Example Manifest
---
applications:
- buildpacks:
- ruby_buildpack
- java_buildpack
env:
VAR1: value1
VAR2: value2
routes:
- route: route.example.com
- route: another-route.example.com
services:
- my-service1
- my-service2
- name: my-service-with-arbitrary-params
parameters:
key1: value1
key2: value2
stack: cflinuxfs3
metadata:
annotations:
contact: "bob@example.com jane@example.com"
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
timeout: 10
- type: worker
command: start-worker.sh
disk_quota: 1G
health-check-type: process
instances: 2
memory: 256M
timeout: 15
sidecars:
- name: authenticator
process_types: [ 'web', 'worker' ]
command: bundle exec run-authenticator
memory: 800M
- name: upcaser
process_types: [ 'worker' ]
command: ./tr-server
memory: 900M
App-level configuration
This configuration is specified at the top-level and applies to all of the app’s processes.
| Field | Description |
|---|---|
| buildpacks | Must be an Array. 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. |
| env | A key-value hash of environment variables to be used for the app when running. |
| no-route | Boolean value. When set to true, any routes specified with the routes attribute will be ignored and any existing routes will be removed; ignored if false. |
| processes | List of configurations for individual process types. See Process-level configuration. |
| random-route | Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified. |
| default-route | Boolean value. 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 false, if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored and results in noop. |
| routes | An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path |
| services | An array of service-instances to bind to the app. See Service-level configuration. |
| sidecars | An array of configurations for individual sidecars. See Sidecar-level configuration. |
| stack | The root filesystem to use with the buildpack, for example cflinuxfs3. |
| metadata.labels (experimental) | Labels applied to the app. |
| metadata.annotations (experimental) | Annotations applied to the app. |
| buildpack | DEPRECATED in favor of the buildpacks field above. a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language. b) A URL pointing to a buildpack. c) Name of an installed buildpack. |
Process-level configuration
This configuration is for the individual process. Each process is created if it does not already exist.
With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.
If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.
| Field | Description |
|---|---|
| type | (Required) Process type. The identifier for the processes to be configured. |
| command | The command used to start the process. This overrides start commands from Procfiles and buildpacks. |
| disk_quota | 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 | Endpoint called to determine if the app is healthy. |
| health-check-invocation-timeout | The timeout in seconds for individual health check requests for http and port health checks. |
| health-check-type | Type of health check to perform. none is deprecated and an alias to process. |
| instances | The number of instances to run. |
| memory | 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. |
| timeout | Time in seconds at which the health-check will report failure. |
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.
| Field | Description |
|---|---|
| name | (Required) Service instance name. The name of the service instance to be bound to. |
| parameters | 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.
| Field | Description |
|---|---|
| name | (Required) Sidecar name. The identifier for the sidecars to be configured. |
| command | The command used to start the sidecar. |
| process_types | List of processes to associate sidecar with. |
| memory | Memory in mb that the sidecar will be allocated. |
Generate an app manifest
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: cflinuxfs3
routes:
- route: my-app.example.com
processes:
- type: web
instances: 2
memory: 512M
disk_quota: 1024M
health-check-type: port
Generate a manifest for an app and its underlying processes.
Definition
GET /v3/apps/:guid/manifest
Permitted Roles
| Admin |
| Admin Read-Only |
| Space Developer |
Apply an app manifest
Example Request
curl "https://api.example.org/v3/apps/[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 an app and its underlying processes. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.
Definition
POST /v3/apps/:guid/actions/apply_manifest
Permitted Roles
| Admin |
| Space Developer |
App Restart
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": "cflinuxfs3"
}
},
"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/restart
Permitted roles
| Admin |
| Space Developer |
Organization Quotas
Organization quotas are named sets of memory, 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,
"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 | datetime | The time with zone when the organization quota was created. |
| updated_at | datetime | 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 of all the started processes and running tasks in an organization. |
| apps.total_instances | integer or nul |
Total instances of all the started processes in an organization. |
| apps.per_app_tasks | integer or nul |
Maximum number of running tasks in a single application. |
| 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 nul |
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. |
| relationships.organizations | to-many relationship | A relationship to the organizations the quota applies to. |
| 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,
"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.
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 | Maximum memory for a single process or task. | null (infinite) |
| apps.total_memory_in_mb | integer | Total memory of all the started processes and running tasks in an organization. | null (infinite) |
| apps.total_instances | integer | Total instances of all the started processes in an organization. | null (infinite) |
| apps.per_app_tasks | integer | Maximum number of running tasks in a single application. | null (infinite) |
| services | object | Quotas that affect services. | |
| services.paid_services_allowed | boolean | If instances of paid service plans can be created. | true |
| services.total_service_instances | integer | Total number of service instances in an organization. | null (infinite) |
| services.total_service_keys | integer | Total number of service keys in an organization. | null (infinite) |
| routes | object | Quotas that affect routes. | |
| routes.total_routes | integer | Total number of routes that an organization can have. | null (infinite) |
| routes.total_reserved_ports | integer | Total number of ports that all routes in an organization can reserve. | null (infinite) |
| domains | object | Quotas that affect domains. | |
| domains.total_domains | integer | Total number of domains that can be scoped to an organization. | null (infinite) |
| relationships.organizations | to-many relationship | A relationship to the organizations the quota applies to. | [] |
Permitted roles
| Role | Notes |
|---|---|
| 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,
"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. |
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,
"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,
"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. |
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. |
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.
To apply an organization quota to an organization you must be an admin.
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
| Role | Notes |
|---|---|
| Admin |
Delete an organization quota
Organization_quotas cannot be deleted while associated with 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
| Role | Notes |
|---|---|
| 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,
"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_private_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,
"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" }
}
}
Definition
PATCH /v3/organization_quota/:guid
Permitted roles
| Role | Notes |
|---|---|
| Admin |
Revisions
Revisions represent code used by an application at a specific time. The most recent revision for a running application represents code and configuration currently running in Cloud Foundry.
Revision are created when the following is changed:
A new droplet is created for an app
An app’s environment variables are changed
The custom start command for an app is added or changed
An app rolls back to a prior revision
Each time a new revision is created the reason(s) for the revisions creation will be appended to its description field.
By default the cloud foundry API retains at most 100 revisions per app.
The revision object
Example Revision object
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"version": 1,
"droplet": {
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"processes": {
"web": {
"command": "bundle exec rackup"
}
},
"sidecars": [
{
"name": "auth-sidecar",
"command": "bundle exec sidecar",
"process_types": ["web"],
"memory_in_mb": 300
}
"description": "Initial revision.",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"metadata": {
"labels": { },
"annotations": { }
},
"links": {
"self": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"app": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"environment_variables": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the revision. |
| version | integer | Human-readable identifier for the revision. Starts at 1, increments by 1 for each new revision of the app, and rolls back over to 1 at 9999. |
| droplet | object | The droplet used by a process running the revision. |
| processes | process snapshot object | An object representing process types at this revision. |
| sidecars | array of sidecar snapshot objects ] | The array of sidecars used by processes running the revision. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| description | string | A short description of the reason for revision. |
| relationships.app | to-one relationship | The app the revision is associated with. |
| metadata.labels (experimental) | label object | Labels applied to the revision. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the revision. |
| links | links object | Links to related resources. |
The process snapshot object
Example Process Snapshot object
{
"web": {
"command": "bundle exec rackup"
},
"worker": {
"command": "bundle exec work"
}
}
The process snapshot object is a map of process types to objects. Each object contains the command that the given process type was running at this revision.
The sidecar snapshot object
Example Sidecar Snapshot object
{
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300
}
| Name | Type | Description |
|---|---|---|
| name | string | Human-readable name for the sidecar. |
| command | string | The command used to start the sidecar. |
| process_types | array of strings | A list of process types the sidecar applies to. |
| memory_in_mb | integer | Reserved memory for sidecar. |
Get a revision
Example Request
curl "https://api.example.org/v3/revisions/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"version": 1,
"droplet": {
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"processes": {
"web": {
"command": "bundle exec rackup"
}
},
"sidecars": [
{
"name": "auth-sidecar",
"command": "bundle exec sidecar",
"process_types": ["web"],
"memory_in_mb": 300
}
"description": "Initial revision.",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"metadata": {
"labels": { },
"annotations": { }
},
"links": {
"self": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"app": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"environment_variables": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
}
}
}
Definition
GET /v3/revisions/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
List revisions for an app
Example Request
curl "https://api.example.org/v3/apps/:guid/revisions" \
-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/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"version": 1,
"droplet": {
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"processes": {
"web": {
"command": "bundle exec rackup"
}
},
"sidecars": [
{
"name": "auth-sidecar",
"command": "bundle exec sidecar",
"process_types": ["web"],
"memory_in_mb": 300
}
],
"description": "Initial revision.",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"app": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"environment_variables": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
}
}
}
]
}
Retrieve revisions for an app the user has access to.
Definition
GET /v3/apps/:guid/revisions
Query parameters
| Name | Type | Description |
|---|---|---|
| versions | list of strings | Comma-delimited list of revision versions to filter by. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
| 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. |
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
List deployed revisions for an app
Example Request
curl "https://api.example.org/v3/apps/:guid/revisions/deployed" \
-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/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
},
"last": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
},
"next": null,
"previous": null
},
"resources": [
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"version": 1,
"droplet": {
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"processes": {
"web": {
"command": "bundle exec rackup"
}
},
"sidecars": [
{
"name": "auth-sidecar",
"command": "bundle exec sidecar",
"process_types": ["web"],
"memory_in_mb": 300
}
],
"description": "Initial revision.",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"metadata": {
"labels": {},
"annotations": {}
},
"links": {
"self": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"app": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"environment_variables": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
}
}
}
]
}
Retrieve deployed revisions for an app the user has access to. Deployed revisions are revisions that are linked to started processes in the app.
Definition
GET /v3/apps/:guid/revisions/deployed
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 values are created_at, updated_at. |
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
Update a revision
Example Request
curl "https://api.example.org/v3/revisions/[revguid]" \
-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": "885735b5-aea4-4cf5-8e44-961af0e41920",
"version": 1,
"droplet": {
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
},
"processes": {
"web": {
"command": "bundle exec rackup"
}
},
"sidecars": [
{
"name": "auth-sidecar",
"command": "bundle exec sidecar",
"process_types": ["web"],
"memory_in_mb": 300
}
"description": "Initial revision.",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z",
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information" }
},
"links": {
"self": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
},
"app": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"environment_variables": {
"href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
}
}
}
Definition
PATCH /v3/revisions/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the revision. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the revision. |
Permitted roles
| Admin |
| Space Developer |
Service Bindings
Service bindings are relations between a service instance and an app; to use a service instance with an app, you must first bind them together.
Not all services support binding, as some services deliver value to users directly without integration with an application.
The service binding object
Example Service Binding object
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"type": "app",
"data": {
"credentials": {
"super-secret": "password"
},
"syslog_drain_url": "syslog://drain.url.example.org",
"volume_mounts": []
},
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"service_instance": {
"href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
},
"app": {
"href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
}
}
}
| Name | Type | Description |
|---|---|---|
| type | string | Service binding type. Valid value is app. |
| data | object | Data returned from the service broker for the service instance. Valid values are credentials, syslog_drain_url and (experimental) volume_mounts. |
| guid | uuid | Unique identifier for the service binding. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| links | links object | Links to related resources. |
Create a service binding
Example Request
curl "https://api.example.org/v3/service_bindings" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"type": "app",
"relationships": {
"app": {
"data": {
"guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
}
},
"service_instance": {
"data": {
"guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
}
}
},
"data": {
"parameters": {
"some_object_id": "for_the_service_broker"
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"type": "app",
"data": {
"credentials": {
"super-secret": "password"
},
"syslog_drain_url": "syslog://drain.url.example.org",
"volume_mounts": []
},
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"service_instance": {
"href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
},
"app": {
"href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
}
}
}
Definition
POST /v3/service_bindings
Required parameters
| Name | Type | Description |
|---|---|---|
| type | string | Service binding type. Valid value is app. |
| relationships.app | to-one relationship | A relationship to an app. |
| relationships.service_instance | to-one relationship | A relationship to a service_instance. |
Optional parameters
| Name | Type | Description | Default |
|---|---|---|---|
| data.parameters | object | Additional configuration parameters for the service binding. | {} |
Permitted roles
| Admin |
| Space Developer |
Get a service binding
Example Request
curl "https://api.example.org/v3/service_bindings/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"type": "app",
"data": {
"credentials": {
"super-secret": "password"
},
"syslog_drain_url": "syslog://drain.url.example.org",
"volume_mounts": []
},
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"service_instance": {
"href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
},
"app": {
"href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
}
}
}
Definition
GET /v3/service_bindings/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
List service bindings
Example Request
curl "https://api.example.org/v3/service_bindings" \
-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/service_bindings?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"type": "app",
"data": {
"credentials": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"syslog_drain_url": "syslog://drain.url.example.org",
"volume_mounts": []
},
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"service_instance": {
"href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
},
"app": {
"href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
}
}
},
{
"guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
"type": "app",
"data": {
"credentials": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"syslog_drain_url": "syslog://drain.url.example.org",
"volume_mounts": []
},
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/service_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
},
"service_instance": {
"href": "https://api.example.org/v3/service_instances/8bf356j3-9e18-45b1-3333-124163f31f9e"
},
"app": {
"href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
}
}
}
]
}
This endpoint retrieves the service bindings the user has access to.
Definition
GET /v3/service_bindings
Query parameters
| Name | Type | Description |
|---|---|---|
| app_guids | list of strings | Comma-delimited list of app guids to filter by. |
| service_instance_guids | list of strings | Comma-delimited list of service_instance 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. |
Permitted roles
| All Roles |
Delete a service binding
Example Request
curl "https://api.example.org/v3/service_bindings/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
Definition
DELETE /v3/service_bindings/:guid
Permitted Roles
| Admin |
| Space Developer |
Service Brokers
Service brokers manage the lifecycle of services. On behalf of users, Cloud Controller will interact with service brokers to provision, get access to and manage access to the service offerings and plans they offer.
Admins can create and manage service brokers that are globally available, i.e., the service broker and its associated resources (service offerings and plans) can be made available to all users.
Space Developers can create and manage space-scoped service brokers. A space-scoped broker and its associated resources will only be available in the space the service broker was created.
The service broker object
Example Service Broker object
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"name": "my_service_broker",
"url": "https://example.service-broker.com",
"available": true,
"status": "available",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"service_offerings": {
"href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
}
},
"metadata": {
"labels": {
"type": "dev"
},
"annotations": {}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the service broker. |
| name | string | Name of the service broker. |
| url | string | URL of the service broker. |
| available | boolean | Whether or not the service broker is available. |
| status | string | Availability status of the service broker. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| relationships.space | to-one relationship | The space the service broker is restricted to. Omitted for globally available service brokers. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the service broker. |
| metadata.annotations (experimental) | annotation object | Annotations added to the service broker. |
Create a service broker
Example Request
curl "https://api.example.org/v3/service_brokers" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "my_service_broker",
"url": "https://example.service-broker.com",
"authentication": {
"type": "basic",
"credentials": {
"username": "us3rn4me",
"password": "p4ssw0rd"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
}
}'
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
This endpoint creates a new service broker and a job to synchronize the service offerings and service plans with those in the broker’s catalog. The Location header refers to the created job which syncs the broker with the catalog.
Definition
POST /v3/service_brokers
Required parameters
| Name | Type | Description |
|---|---|---|
| name | string | Name of the service broker. |
| url | string | URL of the service broker. |
| authentication | authentication | Credentials used to authenticate against the service broker. |
Optional parameters
| Name | Type | Description |
|---|---|---|
| relationships.space | to-one relationship | If set, restricts the service broker to the specified space. |
| metadata.labels (experimental) | label object | Labels applied to the service broker. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the service broker. |
The authentication object
| Name | Type | Description |
|---|---|---|
| type | string | Type of the authentication mechanisms that can be used. Valid value is basic. |
| credentials | object | Credentials for given authentication type. |
Example basic authentication
{
"type": "basic",
"credentials": {
"username": "admin",
"password": "secretpassw0rd"
}
}
Basic authentication credentials
| Name | Type | Description |
|---|---|---|
| username | string | The username with which to authenticate against the service broker. |
| password | string | The password with which to authenticate against the service broker. |
Permitted roles
| Admin |
| Space Developer* |
*Space Developers can only create space-scoped brokers. Space-scoped brokers can only be created when the space_scoped_private_broker_creation feature flag is true.
Get a service broker
Example Request
curl "https://api.example.org/v3/service_brokers/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"name": "my_service_broker",
"url": "https://example.service-broker.com",
"available": true,
"status": "available",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"service_offerings": {
"href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
}
},
"metadata": {
"labels": {
"type": "dev"
},
"annotations": {}
}
}
This endpoint retrieves the service broker by GUID.
Definition
GET /v3/service_brokers/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Space Developer (only space-scoped brokers) |
List service brokers
Example Request
curl "https://api.example.org/v3/service_brokers" \
-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/service_brokers?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"name": "my_service_broker",
"url": "https://example.service-broker.com",
"available": true,
"status": "available",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {} ,
"links": {
"self": {
"href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
},
"service_offerings": {
"href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
"name": "another_service_broker",
"url": "https://another-example.service-broker.com",
"available": true,
"status": "available",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/service_brokers/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
},
"service_offerings": {
"href": "https://api.example.org/v3/service_offerings?service_broker_guids=7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
This endpoint retrieves the service brokers the user has access to.
Definition
GET /v3/service_brokers
Query parameters
| Name | Type | Description |
|---|---|---|
| names | list of strings | Comma-delimited list of service broker 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. |
| space_guids | list of strings | Comma-delimited list of space GUIDs 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, name. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Space Developer (only space-scoped brokers) |
Update a service broker
Example Request
curl "https://api.example.org/v3/service_brokers/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "my_service_broker",
"url": "https://example.service-broker.com",
"authentication": {
"type": "basic",
"credentials": {
"username": "us3rn4me",
"password": "p4ssw0rd"
}
},
"metadata": {
"labels": {"key": "value"},
"annotations": {"note": "detailed information"}
}
}'
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
This endpoint updates a broker and creates a job to synchronize the service offerings and service plans with those in the broker’s catalog. The Location header refers to the created job which syncs the broker with the catalog.
Service Brokers that are in the process of being synchronized or deleted cannot be updated.
Definition
PATCH /v3/service_brokers/[guid]
Optional parameters
| Name | Type | Description |
|---|---|---|
| name | string | Name of the service broker. |
| url | string | URL of the service broker. |
| authentication | authentication | Credentials used to authenticate against the service broker. |
| metadata.labels (experimental) | label object | Labels applied to the service broker. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the service broker. |
The authentication object
| Name | Type | Description |
|---|---|---|
| type | string | Type of the authentication mechanisms that can be used. Valid value is basic. |
| credentials | object | Credentials for given authentication type. |
Example basic authentication
{
"type": "basic",
"credentials": {
"username": "admin",
"password": "secretpassw0rd"
}
}
Basic authentication credentials
| Name | Type | Description |
|---|---|---|
| username | string | The username with which to authenticate against the service broker. |
| password | string | The password with which to authenticate against the service broker. |
Permitted roles
| Admin |
| Space Developer (only space-scoped brokers) |
Delete a service broker
Example Request
curl "https://api.example.org/v3/service_brokers/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
This endpoint creates a job to delete an existing service broker. The Location header refers to the created job.
Definition
DELETE /v3/service_brokers/:guid
Permitted roles
| Admin |
| Space Developer (only space-scoped brokers) |
Service Offerings
Service Offerings represent the services offered by Service Brokers. A Service Broker will have one or more Service Offerings. A Service Offering will have one or more Service Plans. Service Offerings and Service Plans are created and updated when a Service Broker is registered or updated.
Visibility of Service Offerings
This table shows the Service Offerings that different roles can see. The Service Offerings that a user can see relate to their Space and Organization roles, regardless of which Space or Organization is being targeted.
A Service Offering can be seen when at least one of its Service Plans can be seen. Service Plans may be configured to be Public, or they may be configured with a relationship to a restricted list of Organizations.
Service Offerings and Service Plans from a space-scoped Service Broker cannot have their visibility configured. They are only visible to members of that Space.
| Role | Public Plans | Restricted Plans | From space-scoped Service Brokers |
|---|---|---|---|
| Admin | All | All | All |
| Admin Read | All | All | All |
| Global Auditor | All | All | All |
| Org Manager | All | In Organisation | None |
| Org Auditor | All | In Organisation | None |
| Org Billing | All | In Organisation | None |
| Space Manager | All | In Organisation | In Space |
| Space Developer | All | In Organisation | In Space |
| Space Auditor | All | In Organisation | In Space |
| Unauthenticated | All* | None | None |
*Unless the hide_marketplace_from_unauthenticated_users feature flag is true
The Service Offering object
Example Service Offering object
{
"guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
"name": "my_service_offering",
"description": "Provides my service",
"available": true,
"tags": ["relational", "caching"],
"requires": [],
"created_at": "2019-11-28T13:44:02Z",
"updated_at": "2019-11-28T13:44:02Z",
"shareable": true,
"broker_catalog": {
"id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
"metadata": {
"shareable": true
},
"features": {
"plan_updateable": true,
"bindable": true,
"instances_retrievable": true,
"bindings_retrievable": true
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
},
"service_plans": {
"href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
},
"service_broker": {
"href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
},
"relationships": {
"service_broker": {
"data": {
"name": "my_service_broker",
"guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the Service Offering. |
| name | string | Name of the Service Offering. |
| description | string | Description of the Service Offering. |
| available | boolean | Whether or not the Service Offering is available. |
| tags | list of strings | Descriptive tags for the Service Offering. |
| requires | list_of_strings | A list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are syslog_drain, route_forwarding and volume_mount. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| shareable | boolean | Whether or not Service Instances of this Service Offering can be shared across Organizations and Spaces. |
| broker_catalog | object | This object contains information obtained from the Service Broker Catalog. |
| broker_catalog.id | string | The identifier that the Service Broker provided for this Service Offering. |
| broker_catalog.metadata | object | Additional information provided by the Service Broker. |
| broker_catalog.features.plan_updateable | boolean | Whether the Service Offering supports upgrade/downgrade for Service Plans by default |
| broker_catalog.features.bindable | boolean | Specifies whether Service Instances of the service can be bound to applications. |
| broker_catalog.features.instances_retrievable | boolean | Specifies whether the Fetching a Service Instance endpoint is supported for all Service Plans. |
| broker_catalog.features.bindings_retrievable | boolean | Specifies whether the Fetching a Service Binding endpoint is supported for all Service Plans. |
| relationships.service_broker | to-one relationship | The Service Broker that provides this Service Offering. |
| links | links object | Links to related resources. |
| metadata.labels (experimental) | label object | Labels applied to the Service Offering. |
| metadata.annotations (experimental) | annotation object | Annotations added to the Service Offering. |
Get a Service Offering
Example Request
curl "https://api.example.org/v3/service_offerings/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
"name": "my_service_offering",
"description": "Provides my service",
"available": true,
"tags": ["relational", "caching"],
"requires": [],
"created_at": "2019-11-28T13:44:02Z",
"updated_at": "2019-11-28T13:44:02Z",
"shareable": true,
"broker_catalog": {
"id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
"metadata": {
"shareable": true
},
"features": {
"plan_updateable": true,
"bindable": true,
"instances_retrievable": true,
"bindings_retrievable": true
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
},
"service_plans": {
"href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
},
"service_broker": {
"href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
},
"relationships": {
"service_broker": {
"data": {
"name": "my_service_broker",
"guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
This endpoint retrieves the service offering by GUID.
Definition
GET /v3/service_offerings/:guid
Permitted roles
| All Roles |
| Unauthenticated Users |
List service offerings
Example Request
curl "https://api.example.org/v3/service_offerings" \
-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/service_offerings?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/service_offerings?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/service_offerings?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
"name": "my_service_offering",
"description": "Provides my service",
"available": true,
"tags": ["relational", "caching"],
"requires": [],
"created_at": "2019-11-28T13:44:02Z",
"updated_at": "2019-11-28T13:44:02Z",
"shareable": true,
"broker_catalog": {
"id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
"metadata": {
"shareable": true
},
"features": {
"plan_updateable": true,
"bindable": true,
"instances_retrievable": true,
"bindings_retrievable": true
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
},
"service_plans": {
"href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
},
"service_broker": {
"href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
},
"relationships": {
"service_broker": {
"data": {
"name": "my_service_broker",
"guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
}
},
{
"guid": "20e6cd62-12bb-11ea-90d1-7bfec2c75bcd",
"name": "other_service_offering",
"description": "Provides another service",
"available": true,
"tags": ["caching"],
"requires": [],
"created_at": "2019-11-29T16:44:02Z",
"updated_at": "2019-11-29T16:44:02Z",
"shareable": true,
"broker_catalog": {
"id": "3cb11822-12bb-11ea-beb1-a350dc7453b9",
"metadata": {
"shareable": true
},
"features": {
"plan_updateable": true,
"bindable": true,
"instances_retrievable": true,
"bindings_retrievable": true
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/service_offerings/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
},
"service_plans": {
"href": "https://api.example.org/v3/service_plans?service_offering_guids=20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
},
"service_broker": {
"href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
},
"relationships": {
"service_broker": {
"data": {
"name": "my_service_broker",
"guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
]
}
This endpoint retrieves the service offerings the user has access to.
Definition
GET /v3/service_offerings
Query parameters
| Name | Type | Description |
|---|---|---|
| names | list of strings | Comma-delimited list of names to filter by. |
| available | boolean | Filter by the available property. Valid values are true or false. |
| service_broker_guids | list of strings | Comma-delimited list of Service Broker GUIDs to filter by. |
| service_broker_names | list of strings | Comma-delimited list of Service Broker names to filter by. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| All Roles |
| Unauthenticated Users |
Update a service offering
Example Request
curl "https://api.example.org/v3/service_offerings/[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": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
"name": "my_service_offering",
"description": "Provides my service",
"available": true,
"tags": ["relational", "caching"],
"requires": [],
"created_at": "2019-11-28T13:44:02Z",
"updated_at": "2019-11-28T13:44:02Z",
"shareable": true,
"broker_catalog": {
"id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
"metadata": {
"shareable": true
},
"features": {
"plan_updateable": true,
"bindable": true,
"instances_retrievable": true,
"bindings_retrievable": true
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
},
"service_plans": {
"href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
},
"service_broker": {
"href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
},
"relationships": {
"service_broker": {
"data": {
"name": "my_service_broker",
"guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
}
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
This endpoint updates a Service Offering with labels and annotations.
Definition
PATCH /v3/service_offerings/[guid]
Optional parameters
| Name | Type | Description |
|---|---|---|
| metadata.labels (experimental) | label object | Labels applied to the service offering. |
| metadata.annotations (experimental) | annotation object | Annotations applied to the service offering. |
Permitted roles
| Admin |
| Space Developer (only for service offerings from space-scoped brokers) |
Delete a service offering
Example Request
curl "https://api.example.org/v3/service_offerings/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
This endpoint deletes a Service Offering. This is typically used to remove orphan Service Offerings from the Cloud Foundry database when they have been removed from the Service Broker catalog, or when the Service Broker has been removed.
Note that this operation only affects the Cloud Foundry database, and no attempt is made to contact the Service Broker.
Definition
DELETE /v3/service_offerings/:guid
Query parameters
| Name | Type | Description |
|---|---|---|
| purge | boolean | If true, any service plans, instances, and bindings associated with this service offering will also be deleted. |
Permitted roles
| Admin |
| Space Developer (only service offerings from space-scoped brokers) |
Service Plans
Service Plans represent the service plans offered by a Service Offering. A Service Offering will have one or more Service Plans. Service Offerings and Service Plans are created and updated when a Service Broker is registered or updated.
The Service Plan object
Example Service Plan object
{
"guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
"name": "my_big_service_plan",
"description": "Big",
"available": true,
"created_at": "2019-11-28T13:44:02Z",
"updated_at": "2019-11-28T13:44:02Z",
"broker_catalog": {
"id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
"metadata": {
"custom-key": "custom-information"
},
"features": {
"plan_updateable": true,
"bindable": true
}
},
"schemas": {
"service_instance": {
"create": {
"parameters": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"billing-account": {
"description": "Billing account number used to charge use of shared fake server.",
"type": "string"
}
}
}
},
"update": {}
},
"service_binding": {
"create": {}
}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the Service Plan. |
| name | string | Name of the Service Plan. |
| description | string | Description of the Service Plan. |
| available | boolean | Whether or not the Service Plan is available. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
| broker_catalog | object | This object contains information obtained from the Service Broker Catalog. |
| broker_catalog.id | string | The identifier that the Service Broker provided for this Service Plan. |
| broker_catalog.metadata | object | Additional information provided by the Service Broker. |
| broker_catalog.features.plan_updateable | boolean | Whether the Service Plan supports upgrade/downgrade for Service Plans by default |
| broker_catalog.features.bindable | boolean | Specifies whether Service Instances of the service can be bound to applications. |
| schemas | object | Schema definitions for Service Instances and Service Bindings for the Service Plan. |
| schemas.service_instance.create | object | Schema definition for Service Instance creation. |
| schemas.service_instance.create.parameters | JSON Schema object | The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object. |
| schemas.service_instance.update | object | Schema definition for Service Instance update. |
| schemas.service_instance.update.parameters | JSON Schema object | The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object. |
| schemas.service_binding.create | object | Schema definition for Service Binding creation. |
| schemas.service_binding.create.parameters | JSON Schema object | The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object. |
List service plans
Example Request
curl "https://api.example.org/v3/service_plans" \
-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/service_plans?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/service_plans?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/service_plans?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
"name": "my_big_service_plan",
"description": "Big plan",
"available": true,
"created_at": "2019-11-28T13:44:02Z",
"updated_at": "2019-11-28T13:44:02Z",
"broker_catalog": {
"id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
"metadata": {
"custom-key": "custom-value"
},
"features": {
"plan_updateable": true,
"bindable": true
}
},
"schemas": {
"service_instance": {
"create": {
"parameters": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"billing-account": {
"description": "Billing account number used to charge use of shared fake server.",
"type": "string"
}
}
}
},
"update": {}
},
"service_binding": {
"create": {}
}
}
},
{
"guid": "20e6cd62-12bb-11ea-90d1-7bfec2c75bcd",
"name": "other_service_plan",
"description": "Provides another service plan",
"available": true,
"created_at": "2019-11-29T16:44:02Z",
"updated_at": "2019-11-29T16:44:02Z",
"broker_catalog": {
"id": "3cb11822-12bb-11ea-beb1-a350dc7453b9",
"metadata": {
"other-data": true
},
"features": {
"plan_updateable": true,
"bindable": true
}
},
"schemas": {
"service_instance": {
"create": {},
"update": {}
},
"service_binding": {
"create": {}
}
}
}
]
}
This endpoint retrieves the service plans the user has access to.
Definition
GET /v3/service_plans
Permitted roles
| All Roles |
Unauthenticated Users (for public plans, unless hide_marketplace_from_unauthenticated_users is set) |
Sidecars
Sidecars are additional operating system processes that are run in the same container as a process.
Use cases for sidecars
Sidecars are useful for any app processes that need to communicate with another within the same container or are otherwise dependent on each other. Some use cases are:
- Two or more processes that require access to a shared file
- An Application Performance Monitoring (APM) tool that attaches to a dependent app’s processes
- Two or more processes that communicate via a local socket
Steps to create a sidecar
The recommended way to create sidecars for your app is with an app manifest.
sidecars:
- name: authenticator
process_types: [ 'web', 'worker' ]
command: bundle exec run-authenticator
- name: performance monitor
process_types: [ 'web' ]
command: bundle exec run-performance-monitor
memory: 128M
- name is a user defined identifier (unique per app)
- process_types is a list of app processes the sidecar will attach to. You can attach multiple sidecars to each process type your app uses
- command is the command used to start the sidecar
- memory is the memory reserved for the sidecar[1]
1 Applies for Java apps. If you do not reserve memory for the sidecar, the JVM will consume all of the memory in the app container. This value must be less thatn the process’ reserved memory.
Current limitations
- Start and stop order of app processes and their sidecars is undefined
- App processes and sidecar processes are codependent: if either crashes or exits, the other will as well
- Sidecars are currently not independently scalable (memory / disk) and share resources with the main app process and other sidecars within that container
- Sidecars only support PID based health checks; HTTP health-checks for sidecars are not currently supported
- This has only been tested on Linux based systems
The sidecar object
Example Sidecar object
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300,
"origin": "user",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z"
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the sidecar. |
| name | string | Human-readable name for the sidecar. |
| command | string | The command used to start the sidecar. |
| process_types | array of strings | A list of process types the sidecar applies to. |
| memory_in_mb | integer | Reserved memory for sidecar. |
| origin | string | Specifies whether the sidecar was created by the user or via the buildpack. |
| relationships.app | to-one relationship | The app the sidecar is associated with. |
| created_at | datetime | The time with zone when the object was created. |
| updated_at | datetime | The time with zone when the object was last updated. |
Create a sidecar associated with an app
Example Request
curl "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/sidecars" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300,
"origin": "user",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z"
}
Definition
POST /v3/apps/:guid/sidecars
Required parameters
| Name | Type | Description |
|---|---|---|
| name | string | Human-readable name for the sidecar. |
| command | string | The command used to start the sidecar. |
| process_types | array of strings | A list of process types the sidecar applies to. |
Optional parameters
| Name | Type | Description |
|---|---|---|
| memory_in_mb | integer | Reserved memory for sidecar. |
Permitted roles
| Admin |
| Space Developer |
Get a sidecar
Example Request
curl "https://api.example.org/v3/sidecars/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300,
"origin": "user",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z"
}
Definition
GET /v3/sidecars/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
Update a sidecar
Example Request
curl "https://api.example.org/v3/sidecars/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-H "Content-Type: application/json" \
-d '{
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300
}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300,
"origin": "user",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z"
}
Definition
PATCH /v3/sidecars/:guid
Optional parameters
| Name | Type | Description |
|---|---|---|
| name | string | Human-readable name for the sidecar. |
| command | string | The command used to start the sidecar. |
| process_types | array of strings | A list of process types the sidecar applies to. |
| memory_in_mb | integer | Reserved memory for sidecar. |
Permitted roles
| Admin |
| Space Developer |
List sidecars for app
Example Request
curl "https://api.example.org/v3/apps/[guid]/sidecars" \
-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/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300,
"origin": "user",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z"
},
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
"name": "echo-sidecar",
"command": "start-echo-server",
"process_types": ["web"],
"memory_in_mb": 300,
"origin": "user",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:59Z",
"updated_at": "2017-02-01T01:33:59Z"
}
]
}
Retrieves all sidecars associated with a app.
Definition
GET /v3/apps/:guid/sidecars
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 values are created_at, updated_at. |
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
List sidecars for process
Example Request
curl "https://api.example.org/v3/processes/[guid]/sidecars" \
-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/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
"name": "auth-sidecar",
"command": "bundle exec rackup",
"process_types": ["web", "worker"],
"memory_in_mb": 300,
"origin": "user",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:58Z",
"updated_at": "2017-02-01T01:33:58Z"
},
{
"guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
"name": "echo-sidecar",
"command": "start-echo-server",
"process_types": ["web"],
"memory_in_mb": 300,
"origin": "user",
"relationships": {
"app": {
"data": {
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
}
}
},
"created_at": "2017-02-01T01:33:59Z",
"updated_at": "2017-02-01T01:33:59Z"
}
]
}
Retrieves all sidecars associated with a process.
Definition
GET /v3/processes/:guid/sidecars
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 values are created_at, updated_at. |
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
Delete a sidecar
Example Request
curl "https://api.example.org/v3/sidecars/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
Definition
DELETE /v3/sidecars/:guid
Permitted roles
| Admin |
| Space Developer |
Space Manifest
The space manifest is a method for applying bulk configurations to apps and their underlying processes.
The space manifest specification
Example Manifest
---
applications:
- name: app1
buildpacks:
- ruby_buildpack
- java_buildpack
env:
VAR1: value1
VAR2: value2
routes:
- route: route.example.com
- route: another-route.example.com
services:
- my-service1
- my-service2
- name: my-service-with-arbitrary-params
parameters:
key1: value1
key2: value2
stack: cflinuxfs3
metadata:
annotations:
contact: "bob@example.com jane@example.com"
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
timeout: 10
- type: worker
command: start-worker.sh
disk_quota: 1G
health-check-type: process
instances: 2
memory: 256M
timeout: 15
- name: app2
env:
VAR1: value1
processes:
- type: web
instances: 1
memory: 256M
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
| Field | Description |
|---|---|
| applications | An array of App configurations |
App-level configuration
This configuration is specified at the top-level and applies to all of the app’s processes.
| Field | Description |
|---|---|
| buildpacks | Must be an Array. 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 | 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 | A key-value hash of environment variables to be used for the app when running. |
| no-route | Boolean value. When set to true, any routes specified with the routes attribute will be ignored and any existing routes will be removed; ignored if false. |
| processes | List of configurations for individual process types. See Process-level configuration. |
| random-route | Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified. |
| default-route | Boolean value. 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 false, if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored and results in noop. |
| routes | An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path |
| services | An array of service-instances to bind to the app. See Service-level configuration. |
| sidecars | An array of configurations for individual sidecars. See Sidecar-level configuration. |
| stack | The root filesystem to use with the buildpack, for example cflinuxfs3. |
| metadata.labels (experimental) | Labels applied to the app. |
| metadata.annotations (experimental) | Annotations applied to the app. |
| buildpack | DEPRECATED in favor of the buildpacks field above. a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language. b) A URL pointing to a buildpack. c) Name of an installed buildpack. |
Process-level configuration
This configuration is for the individual process. Each process is created if it does not already exist.
With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.
If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.
| Field | Description |
|---|---|
| type | (Required) Process type. The identifier for the processes to be configured. |
| command | The command used to start the process. This overrides start commands from Procfiles and buildpacks. |
| disk_quota | 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 | Endpoint called to determine if the app is healthy. |
| health-check-invocation-timeout | The timeout in seconds for individual health check requests for http and port health checks. |
| health-check-type | Type of health check to perform. none is deprecated and an alias to process. |
| instances | The number of instances to run. |
| memory | 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. |
| timeout | Time in seconds at which the health-check will report failure. |
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.
| Field | Description |
|---|---|
| name | (Required) Service instance name. The name of the service instance to be bound to. |
| parameters | 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.
| Field | Description |
|---|---|
| name | (Required) Sidecar name. The identifier for the sidecars to be configured. |
| command | The command used to start the sidecar. |
| process_types | List of processes to associate sidecar with. |
| memory | Memory in mb that the sidecar will be allocated. |
Apply a space manifest
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. 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 |
Space Quotas
Space quotas are named sets of quotas. Space quota names are unique within an organization. For example, an organization may only have one space quota named “production”, but two organizations may have two distinct space quotas, both named “production”.
Only one space quota may be applied to a given space at any given time.
Space quotas cannot be used to bypass organization quotas. When the organization’s quota and the space’s quota specify a different values for a given resource, the more restrictive of the two is used. In the event of permissions, the more restrictive permission is used.
The space quota object
Example Space Quota object
{
"guid": "9b370018-c38e-44c9-86d6-155c76801104",
"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,
"total_instances": 10,
"per_app_tasks": null
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 20
},
"relationships": {
"organizations": {
"data": {
"guid": "9b370018-c38e-44c9-86d6-155c76801104"
}
},
"spaces": {
"data": [
{
"guid": "45bb0018-c38e-44c9-86d6-155c76803600"
}
]
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organization_quotas/9b370018-c38e-44c9-86d6-155c76801104"
},
"organization": {
"href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
}
}
}
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the space quota. |
| created_at | datetime | The time with zone when the space quota was created. |
| updated_at | datetime | The time with zone when the space 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 of all the started processes and running tasks that a space can have. |
| apps.total_instances | integer or null |
Total instances of all the started processes that a space can have. |
| apps.per_app_tasks | integer or null |
Maximum number of running tasks in a single application. |
| 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 that a space can have. |
| services.total_service_keys | integer or null |
Total number of service keys that a space can have. |
| routes | object | Quotas that affect routes. |
| routes.total_routes | integer or null |
Total number of routes that a space can have. |
| routes.total_reserved_ports | integer or null |
Total number of ports that can be reserved by routes in a space. |
| relationships.organization | to-one relationship | A relationship to the organization where the quota belongs. |
| relationships.spaces | to-many relationship | A relationship to the spaces to which the quota is applied. |
| links | links object | Links to related resources. |
Create a space quota
Example Request
curl "https://api.example.org/v3/space_quotas" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "production",
"relationships": {
"organization": {
"data": {
"guid": "[org-guid]"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "9b370018-c38e-44c9-86d6-155c76801104",
"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,
"total_instances": 10,
"per_app_tasks": null
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 20
},
"relationships": {
"organizations": {
"data": {
"guid": "9b370018-c38e-44c9-86d6-155c76801104"
}
},
"spaces": {
"data": [
{
"guid": "45bb0018-c38e-44c9-86d6-155c76803600"
}
]
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organization_quotas/9b370018-c38e-44c9-86d6-155c76801104"
},
"organization": {
"href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
}
}
}
This endpoint creates a new space quota scoped to a specific organization.
Definition
POST /v3/space_quotas
Required parameters
| Name | Type | Description |
|---|---|---|
| name | string | Name of the quota. |
| relationships.organization | to-one relationship | A relationship to the organization to which the quota belongs. |
Optional parameters
| Name | Type | Description | Default |
|---|---|---|---|
| apps | object | Quotas that affect applications and application sub-resources. | |
| apps.per_process_memory_in_mb | integer | Maximum memory for a single process or task. | null (infinite) |
| apps.total_memory_in_mb | integer | Total memory of all the started processes and running tasks in a space. | null (infinite) |
| apps.total_instances | integer | Total instances of all the started processes in a space. | null (infinite) |
| apps.per_app_tasks | integer | Maximum number of running tasks in a single application. | null (infinite) |
| services | object | Quotas that affect services. | |
| services.paid_services_allowed | boolean | If instances of paid service plans can be created. | true |
| services.total_service_instances | integer | Total number of service instances in a space. | null (infinite) |
| services.total_service_keys | integer | Total number of service keys in a space. | null (infinite) |
| routes | object | Quotas that affect routes. | |
| routes.total_routes | integer | Total number of routes that a space can have. | null (infinite) |
| routes.total_reserved_ports | integer | Total number of ports that all routes in a space can reserve. | null (infinite) |
| relationships.spaces | to-many relationship | A relationship to the spaces to which the quota is applied. |
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Org Manager | Org managers can create space quotas in their managed organizations. |
Get a space quota
Example Request
curl "https://api.example.org/v3/space_quotas/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "9b370018-c38e-44c9-86d6-155c76801104",
"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,
"total_instances": 10,
"per_app_tasks": null
},
"services": {
"paid_services_allowed": true,
"total_service_instances": 10,
"total_service_keys": 20
},
"routes": {
"total_routes": 8,
"total_reserved_ports": 20
},
"relationships": {
"organizations": {
"data": {
"guid": "9b370018-c38e-44c9-86d6-155c76801104"
}
},
"spaces": {
"data": [
{
"guid": "45bb0018-c38e-44c9-86d6-155c76803600"
}
]
}
},
"links": {
"self": {
"href": "https://api.example.org/v3/organization_quotas/9b370018-c38e-44c9-86d6-155c76801104"
},
"organization": {
"href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
}
}
}
Definition
GET /v3/space_quotas/:guid
Permitted roles
| Role | Notes |
|---|---|
| Admin | |
| Admin Read-Only | |
| Global Auditor | |
| Org Manager | Can see space quotas owned by the organization where they have this role |
| Space Auditor | Can see space quotas applied to the space where they have this role |
| Space Developer | Can see space quotas applied to the space where they have this role |
| Space Manager | Can see space quotas applied to the space where they have this role |
Upgrade Guide
This document is intended to help client authors upgrade from Cloud Foundry’s V2 API to the V3 API.
When moving to the V3 API, it is important to understand that the V3 API is backed by the same data as the V2 API. Though resources may be presented differently and have different interaction patterns, the internal state of CF will be the same across both APIs.
If you have questions, need help, or want to chat about the upgrade process, please reach out to us in Cloud Foundry Slack.
Changed Resources
This table shows how V2 resources map to their respective V3 counterparts. Note that some V2 resources have split into multiple V3 resources, and some V2 resources have been combined into a single resource on V3. As these resources are currently under active development, these mappings may change.
| V2 Resource(s) | V3 Resource(s) | Details |
|---|---|---|
| Apps | Apps, Builds, Droplets, Packages, Processes | |
| Buildpacks | Buildpacks | |
| Domains, Shared Domains, Private Domains | Domains | Domains in V3 |
| Environment Variable Groups | Environment Variable Groups | |
| Events | Audit Events | |
| Feature Flags | Feature Flags | |
| Jobs | Jobs | |
| Organizations | Organizations | |
| Quota Definitions | Organization Quotas | |
| Resource Matches | Resource Matches | |
| Routes, Route Mappings | Routes | Routes in V3 |
| Security Groups | Security Groups | |
| Service Bindings, Service Keys | Service Keys | |
| Service Brokers | Service Brokers | |
| Service Instances, User-Provided Service Instances | Service Instances | |
| Spaces | Spaces | |
| Space Quota Definitions | Space Quotas | |
| Stacks | Stacks | |
| Usage Events | Usage Events | |
| Users | Roles, Users | Users and Roles in V3 |
Domains in V3
In V2, there were two types of domains exposed via different endpoints: private domains and shared domains.
In V3, there is only one domain resource. A domain is “shared” if it has an “owning organization”, which is the organization in which the domain is accessible. This is represented as a relationship to this organization. A domain is “private” if it doesn’t have this relationship.
Read more about the domain resource.
Routes in V3
In V2, the route resource represented a URL that could be mapped to an app, and the route mapping resource represented a mapping between a route and an app.
In V3, these concepts have been collapsed into a single route resource. Now, a route can have one or more “destinations” listed on it. These represent a mapping from the route to a resource that can serve traffic (e.g. a process of an app).
Read more about routes and destinations.
Users and Roles in V3
The user resource remains largely unchanged from the v2 API. On v2, GET /v2/users was restricted to admins, and other users needed to use nested endpoints (GET /v2/organizations/:guid/user and GET /v2/spaces/:guid/user) to view user resources. On v3, GET /v3/users is now available for all users, similar to other resources. Note that this does not change what user resources are visible.
In V2, roles were modeled as associations between organization and space endpoints. In V3, roles have a dedicated resource: /v3/roles. This has changed the manner in which roles are assigned. For example, in V2, to assign a user the org_manager role, one would PUT /v2/organizations/:org_guid/managers/:user_id. In V3, one would POST /v3/roles with the role type and relationships to the user and organization.
Read more about users and roles.
Conceptual Changes
App Sub-Resources
The V2 API rolls up several resources into its representation of an “app”:
- Packages: Source assets for the application
- Droplets: Staged, executable assets for the application
- Builds: Configuration for how to stage the package into a droplet
- Processes: Configuration for how to run the droplet
The V3 API exposes these resources on the API to provide more visibility and enable more complicated workflows. For example:
- Staging a previous package into a new droplet
- Rolling back to a previous droplet
- Staging a droplet to run a task, without running any processes
- Running multiple different processes from a single droplet (for example: a web process and a worker process)
Here are some examples of implications for clients:
- The app resource contains much less information about the application as a whole
- An application can have multiple processes, each with their own start command, scale, and stats
- An application might not be running with its most recent package or droplet
Asynchronous Operations
Unlike V2, clients cannot opt-in for asynchronous responses from endpoints. Instead, endpoints that require asynchronous processing will return 202 Accepted with a Location header pointing to the job resource to poll. Endpoints that do not require asynchronous processing will respond synchronously.
For clients that want to report the outcome of an asynchronous operation, the expected pattern is to poll the job in the Location header until its state is no longer PROCESSING. If the job’s state is FAILED, the errors field will contain any errors that occurred during the operation.
An example of an asynchronous endpoint is the delete app endpoint.
Read more about the job resource.
Errors
Example Request
curl "https://api.example.org/v2/apps/not-found" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"description": "The app could not be found: not-found",
"error_code": "CF-AppNotFound",
"code": 100004
}
Example Request
curl "https://api.example.org/v3/apps/not-found" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"detail": "App not found",
"title": "CF-ResourceNotFound",
"code": 10010
}
]
}
The V3 API returns an array of errors instead of a single error like in V2.
Clients may wish to display all returned errors.
Filtering
Filters are specified as individual query parameters in V3
curl "https://api.example.org/v2/apps?q=name+IN+dora,broker;stack:cflinuxfs3" \
-X GET \
-H "Authorization: bearer [token]"
curl "https://api.example.org/v3/apps?names=dora,broker&stacks=cflinuxfs3" \
-X GET \
-H "Authorization: bearer [token]"
Filtering resources no longer uses V2’s query syntax. See the example to the right.
A few common filters have been also renamed in V3:
| V2 filter | V3 filter |
|---|---|
results-per-page |
per_page |
page |
page |
order-by |
order_by |
order-direction |
N/A1 |
1 In V3, order is ascending by default. Prefix the order_by value with - to make it descending. For example, ?order_by=-name would order a list of resources by name in descending order.
Read more about filtering in V3.
Including Associated Resources
The inline-relations-depth parameter is no longer supported on V3. Instead, some resources support the include parameter to selectively include associated resources in the response body.
For example, to include an app’s space in the response:
cf curl /v3/apps/:guid?include=space
Read more about the include parameter.
New Concepts
Actions
Actions are API requests that are expected to immediately initiate change within the Cloud Foundry runtime. This is differentiated from requests which update a record but require additional updates, such as restarting an app, to cause changes to a resource to take effect.
Example:
POST /v3/apps/:guid/actions/start
Links
Example Request
curl "https://api.example.org/v3/apps/:guid" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
{
"...": "...",
"links": {
"self": {
"href": "http://api.example.com/v3/apps/:guid"
},
"space": {
"href": "http://api.example.com/v3/spaces/:space_guid"
}
}
}
Links provide URLs to associated resources, relationships, and actions for a resource. The example links to both the app itself and the space in which it resides.
Metadata
Example Request
curl "https://api.example.org/v3/:resource/:guid" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
{
"...": "...",
"metadata": {
"labels": {
"environment": "production",
"internet-facing": "false"
},
"annotations": {
"contacts": "Bill tel(1111111) email(bill@fixme)"
}
}
}
Metadata allows you to tag and query certain API resources with information; metadata does not affect the resource’s functionality.
For more details and usage examples, see metadata or official CF docs.
Note that metadata consists of two keys, labels and annotations, each of which consists of key-value pairs. API V3 allows filtering by labels (see label_selector) but not by annotations.
Relationships
Example Request
curl "https://api.example.org/v3/apps" \
-X POST \
-H "Authorization: bearer [token]"
-d '{
"name": "testapp",
"relationships": {
"space": { "data": { "guid": "1234" }}
}
}'
Relationships represent associations between resources: For example, every space belongs in an organization, and every app belongs in a space. The V3 API can create, read, update, and delete these associations.
In the example request we create an app with a relationship to a specific space.
One can retrieve or update a resource’s relationships. For example, to retrieve an app’s relationship to its space with the /v3/apps/:app_guid/relationships/space endpoint.
For more information, refer to the relationships.
New Resources
The V3 API introduces new resources that are not available on the V2 API. Below are brief descriptions of these resources. This is not intended to be an exhaustive list and may not be updated as new resources are added to V3.
Note: Some of these resources may still be experimental and are subject to change or removal without warning. For up to date information on which resources are still experimental see Experimental Resources.
App Features
App features support enabling/disabling behaviors for an individual app.
Read more about the app feature resource.
Deployments
Deployments are objects that manage updates to applications with zero downtime.
Read more about the deployment resource.
Isolation Segments
Isolation segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.
Read more about the isolation segment resource.
Manifests
Manifests are a method for providing bulk configuration to applications and other resources in a space.
Read more about the app manifest and space manifest resources.
Revisions
Revisions represent code and configuration used by an application at a specific time. The most recent revision for a running application represents the code and configuration currently running in Cloud Foundry.
Read more about the revision resource.
Sidecars
Sidecars are additional programs that are run in the same container as a process.
Read more about the sidecar resource.
Tasks
Tasks are one-off jobs that are intended to execute a droplet, stop, and be cleaned up, freeing up resources.
Examples of this include database migrations and running batch jobs.
Read more about the task resource.