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 from 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 the team 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 | Provide 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 will always contain at least 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. User Roles are currently managed by the V2 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 Member | 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 that return lists of resources support filtering down the returned resources using 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.
Combined filters
GET /v3/apps?names=the_name&state=STARTED
This will return all apps with name the_name AND state STARTED.
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 ensure that information about the parent object(s) is part of 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 |
| 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. Annotations are not queryable, non-identifying attributes of a resource, and they do not affect the operation of CloudFoundry.
Examples may include (but are not limited to):
"contact info": "[email protected] [email protected]""library versions": "Spring: 5.1, Redis Client: a184098. yaml parser: 38""git-sha": "d56fe0367554ae5e878e37ed6c5b9a82f5995512"
Annotation 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 ,
-,_, and. - Must begin and end with an alphanumeric character
Annotation value
Annotation values must adhere to the following restrictions:
- Length: 0-5000 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,
-, 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 ,
-,_, 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 ,
-,_, 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.
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.
Not all resources implement every relationship operation listed below. See the docs for each resource to see how it interacts with its relationships.
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 an 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 upstream service caused the request to fail. |
Workflows
Many users will think of interactions with Cloud Foundry in terms of a single operation like cf push in order to upload an application to the platform, have it compiled, and schedule it to be run.
Performing a push operation actually requires a client to orchestrate several requests to the API to accomplish the entire operation.
This section is meant to explain how clients can perform complex workflows using the API.
Push V2 app and run a V3 task
As of CF-245, a V2 application is also available as a V3 application, allowing a user to run a V3 task against it.
- Push an application:
cf push v3-tasks-sample - Construct a task creation curl:
cf curl /v3/apps/$(cf app v3-tasks-sample --guid)/tasks -X POST -d '{"command":"echo foo; sleep 5; echo bar;"}' - Get logs from task:
cf logs v3-tasks-sample --recent - Check task state:
cf curl /v3/apps/$(cf app v3-tasks-sample --guid)/tasks
For more information, see Create a task.
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"
}
},
"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 lifecycle object for the application. |
| 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"
}
},
"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"
}
},
"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"
}
},
"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"
}
},
"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"
}
},
"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 |
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"
}
},
"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"
}
},
"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"
}
}'
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 |
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": "[email protected]"
},
"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 | An object describing the lifecycle that was configured or discovered from the app. |
| 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": "[email protected]"
},
"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": "[email protected]"
},
"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": "[email protected]"
},
"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": "[email protected]"
},
"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": "[email protected]"
},
"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 |
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 with the internal param |
|
| 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 configured or discovered from the app. lifecycle.data will always be an empty hash for a droplet object. |
| 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 |
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 |
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"
}
},
"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"
}
},
"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"
}
},
"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"
}
},
"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"
}
},
"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"
}
},
"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"
}
},
"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"
}
},
"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
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 |
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",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"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. |
| 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. |
| 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. |
| 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",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"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",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"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
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",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"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. |
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",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"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",
"host": "a-hostname",
"path": "/some_path",
"url": "a-hostname.a-domain.com/some_path",
"created_at": "2019-05-10T17:17:48Z",
"updated_at": "2019-05-10T17:17:48Z",
"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
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"
}
}
},
"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. |
| 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"
}
}
},
"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"
}
}
},
"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"
}
}
},
"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"
}
}
},
"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"
}
},
"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"
}
}
},
"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
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 |
Experimental Resources
App Features
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 (experimental) |
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 |
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: "[email protected] [email protected]"
labels:
sensitive: true
processes:
- type: web
command: start-web.sh
disk_quota: 512M
health-check-http-endpoint: /healthcheck
health-check-type: http
health-check-invocation-timeout: 10
instances: 3
memory: 500M
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"
}
},
"metadata": {
"labels": {},
"annotations": {}
}
}
Definition
POST /v3/apps/:guid/actions/restart
Permitted roles
| Admin |
| Space Developer |
App SSH Enabled
Get app SSH enabled
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"
}
Definition
GET /v3/apps/:guid/ssh_enabled
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Org Manager |
| Space Auditor |
| Space Developer |
| Space Manager |
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": "DEPLOYING",
"reason": null
},
"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 DEPLOYING, CANCELING, and FINALIZED (meaning finished, either successfully or not). |
| status.reason | string or null |
The reason for the final status of the deployment. Valid values are DEPLOYED, CANCELED, SUPERSEDED (another deployment created for app before completion), DEGENERATE (the deployment was created incorrectly by the system). This attribute is only set if the deployment has status.value of FINALIZED. If the deployment is still in progress, this field will be set to null. |
| 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]"
},
"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]"
},
"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": "DEPLOYING",
"reason": null
},
"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 | |
| 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": "DEPLOYING",
"reason": null
},
"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"
},
"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 DEPLOYED, CANCELED, SUPERSEDED, and a blank value. |
| status_values | list of strings | Comma-delimited list of status values to filter by. Valid values include DEPLOYING 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": "DEPLOYING",
"reason": null
},
"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 |
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 |
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 services and plans they offer.
The service broker object
Example Service Broker object
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"name": "my_service_broker",
"url": "https://example.service-broker.com",
"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"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
}
| 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. |
| 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. |
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",
"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"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
}
This endpoint retrieves the service broker by GUID.
Definition
GET /v3/service_brokers/:guid
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Space Developer |
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",
"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"
}
}
},
{
"guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
"name": "another_service_broker",
"url": "https://another-example.service-broker.com",
"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"
},
"space": {
"href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
}
]
}
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. |
Permitted roles
| Admin |
| Admin Read-Only |
| Global Auditor |
| Space Developer |
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",
"credentials": {
"type": "basic",
"data": {
"username": "us3rn4me",
"password": "p4ssw0rd"
}
},
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
}
}'
Example Response
HTTP/1.1 202 Created
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 | Default |
|---|---|---|---|
| space | to-one relationship | If set, restricts broker visibility to the specified space. | null |
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
| Space Developer |
| Admin |
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 204 No Content
Content-Type: application/json
This endpoint deletes an existing service broker.
Definition
DELETE /v3/service_brokers/:guid
Permitted roles
| Admin |
| Space Developer |
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: "[email protected] [email protected]"
labels:
sensitive: true
processes:
- type: web
command: start-web.sh
disk_quota: 512M
health-check-http-endpoint: /healthcheck
health-check-type: http
health-check-invocation-timeout: 10
instances: 3
memory: 500M
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 |
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
| Admin |
| Admin Read-Only |
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. For users without the admin or admin_read_only roles, this will just return the current user.
Definition
GET /v3/users
Query parameters
| Name | Type | Description |
|---|---|---|
| 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. |
| label_selector | string | Experimental - A query string containing a list of label selector requirements. |
Permitted roles
| All Roles |
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
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 |