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
Concepts
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 |
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. |
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
| Name | Type | Description |
|---|---|---|
| href | string | The absolute URL. |
| method | string | An optional field containing the HTTP method to be used when following the URL. |
Relationships
Relationships represent associations between resources. Relationships can be used to create, read, update, and delete associations through the relationship sub resource.
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 object | 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]"
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. |
Pagination
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
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"
}
}
}
]
}
| 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. |
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
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 cflinuxfs2 |
Docker lifecycle
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 {}. |
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.
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
| 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. |
| space (experimental) | to-one relationship | The space the app is contained in. |
| links | links object | Links to related resources. |
Create an app
Example Request
curl "https://api.example.org/v3/apps" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"name": "my_app",
"relationships": {
"space": {
"data": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"state": "STOPPED",
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-06-08T16:41:26Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": ["java_buildpack"],
"stack": "cflinuxfs2"
}
},
"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"
},
"route_mappings": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
},
"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"
}
}
}
Definition
POST /v3/apps
Required Parameters
| Name | Type | Description |
|---|---|---|
| name | string | Name of the app. |
| 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 |
Permitted Roles
| Space Developer |
| Admin |
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": "cflinuxfs2"
}
},
"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"
},
"route_mappings": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
},
"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"
}
}
}
Definition
GET /v3/apps/:guid
Permitted Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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": "cflinuxfs2"
}
},
"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"
},
"route_mappings": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
},
"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"
}
}
}
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. |
Permitted Roles
| Space Developer |
| Admin |
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
| Space Developer |
| Admin |
| Admin Read-Only |
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
| Space Developer |
| Admin |
| Admin Read-Only |
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
| Space Developer |
| Admin |
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
| Space Developer |
| Admin |
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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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"
}
],
"stack": "cflinuxfs2",
"image": null,
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"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"
}
}
}
Definition
GET /v3/apps/:guid/droplets/current
Permitted Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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": "cflinuxfs2"
}
},
"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"
},
"route_mappings": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
},
"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"
}
}
}
Definition
POST /v3/apps/:guid/actions/start
Permitted Roles
| Space Developer |
| Admin |
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": "cflinuxfs2"
}
},
"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"
},
"route_mappings": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
},
"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"
}
}
}
Definition
POST /v3/apps/:guid/actions/stop
Permitted Roles
| Space Developer |
| Admin |
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
| Space Developer |
| Admin |
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": "cflinuxfs2"
}
},
"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"
},
"route_mappings": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
},
"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"
}
}
},
{
"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": "cflinuxfs2"
}
},
"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"
},
"route_mappings": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/route_mappings"
},
"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"
}
}
}
]
}
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. |
| 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. |
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
| 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. |
| links | links object | Links to related resources. |
Create a build
Example Request
curl "https://api.example.org/v3/builds" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"package": {
"guid": "[package-guid]"
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-06-08T16:41:26Z",
"created_by": {
"guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
"name": "bill",
"email": "[email protected]"
},
"state": "STAGING",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpacks": [ "ruby_buildpack" ],
"stack": "cflinuxfs2"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": null,
"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 |
Permitted Roles
| Space Developer |
| Admin |
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": "cflinuxfs2"
}
},
"package": {
"guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
},
"droplet": {
"guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
},
"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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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
| Name | Type | Description |
|---|---|---|
| state | string | State of the droplet. Valid states are 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. |
| 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. |
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 cflinuxfs2 |
Detected buildpack object
| Name | Type | Description |
|---|---|---|
| name | string | Buildpack name |
| detect_output | string | Output during buildpack detect process |
Docker droplet
| Name | Type | Description |
|---|---|---|
| image | string | Docker image name. |
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",
"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"
}
}
}
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 |
|---|---|---|
| app | to-one relationship | A relationship to the destination app. |
Permitted Roles
| Space Developer |
| Admin |
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"
}
],
"stack": "cflinuxfs2",
"image": null,
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"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"
}
}
}
Definition
GET /v3/droplets/:guid
Permitted Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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
| Space Developer |
| Admin |
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"
}
],
"stack": "cflinuxfs2",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"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"
}
}
},
{
"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",
"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"
}
}
}
]
}
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. |
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"
}
],
"stack": "cflinuxfs2",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"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"
}
}
},
{
"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",
"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"
}
}
}
]
}
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. |
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"
}
],
"stack": "cflinuxfs2",
"created_at": "2016-03-28T23:39:34Z",
"updated_at": "2016-03-28T23:39:47Z",
"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"
}
}
},
{
"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",
"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"
}
}
}
]
}
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. |
Isolation Segments
Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.
The isolation_segment object
| 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. |
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"
}
}
}
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. |
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"
}
}
}
Definition
GET /v3/isolation_segments/:guid
Permitted Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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"
}
}
}
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. |
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 |
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"
}
}
},
{
"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"
}
}
},
{
"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"
}
}
},
{
"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"
}
}
},
{
"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"
}
}
}
]
}
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. |
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 |
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
| Org Manager |
| Org Auditor |
| Org Billing Manager |
| Org Member |
| Space Developer |
| Space Manager |
| Space Auditor |
| Admin |
| Admin Read-Only |
| Global Auditor |
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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
Jobs
Jobs are created by the platform when performing certain asynchronous actions.
The job object
| 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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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
| Name | Type | Description |
|---|---|---|
| name | string | Name of the organization. |
| guid | uuid | Unique identifier for 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. |
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",
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
}
}
}
Definition
POST /v3/organizations
Required Parameters
| Name | Type | Description |
|---|---|---|
| name | string | Organization name |
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.
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",
"links": {}
},
{
"guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
"created_at": "2017-02-02T00:14:30Z",
"updated_at": "2017-02-02T00:14:30Z",
"name": "org2",
"links": {}
}
]
}
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. |
| 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. |
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",
"links": {
"self": {
"href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
}
}
}
This endpoint retrieves the specified organization object.
Definition
GET /v3/organizations/:guid
Permitted Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Org Billing Manager |
| Org Auditor |
| Admin |
| Admin Read-Only |
| Global Auditor |
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",
"links": {}
},
{
"guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
"created_at": "2017-02-02T00:14:30Z",
"updated_at": "2017-02-02T00:14:30Z",
"name": "org2",
"links": {}
}
]
}
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. |
| 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. |
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
| Org Manager |
| Admin |
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
| Org Manager |
| Org Auditor |
| Org Billing Manager |
| Org Member |
| Space Developer |
| Space Manager |
| Space Auditor |
| Admin |
| Admin Read-Only |
| Global Auditor |
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
| 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. |
| links | links object | Links to related resources. |
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. |
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. |
Create a package
Example Request (buildpack app)
curl "https://api.example.org/v3/packages" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"type": "bits",
"relationships": {
"app": {
"data": {
"guid": "[guid]"
}
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
"type": "bits",
"data": {
"checksum": {
"type": "sha256",
"value": null
},
"error": null
},
"state": "PROCESSING_UPLOAD",
"created_at": "2015-11-13T17:02:56Z",
"updated_at": "2016-06-08T16:41:26Z",
"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"
}
}
}
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",
"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"
}
}
}
Definition
POST /v3/packages
Required Parameters
| Name | Type | Description |
|---|---|---|
| type | string | Type of the package. Valid values are bits, docker. |
| 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. |
Permitted Roles
| Space Developer |
| Admin |
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",
"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"
}
}
}
Definition
GET /v3/packages/:guid
Permitted Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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" \
-F bits=@"package.zip" \
-X POST \
-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",
"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"
}
}
}
Upload file for a package of type bits. The file must be sent as part of a multi-part form.
Definition
POST /v3/packages/:guid/upload
Required Parameters
| Name | Type | Description |
|---|---|---|
| bits | form field | A binary zip file containing the package bits. |
Permitted Roles
| Space Developer |
| Admin |
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
| Space Developer |
| Admin |
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",
"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"
}
}
}
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 |
|---|---|---|
| app | to-one relationship | A relationship to the destination app. |
Permitted Roles
| Space Developer |
| Admin |
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
| Space Developer |
| Admin |
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=2&per_page=2"
},
"next": {
"href": 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",
"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"
}
}
},
{
"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",
"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"
}
}
}
]
}
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. |
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",
"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"
}
}
}
]
}
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. |
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
| Name | Type | Description |
|---|---|---|
| type | string | Process type. A unique identifier for processes belonging to an app. |
| command | string | The command is used to start the process. |
| 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. |
| 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. |
The health_check object
| 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 the health check can fail before the process is restarted. |
| 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
| 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. |
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
}
},
"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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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
}
]
}
Definition
GET /v3/processes/:guid/stats
GET /v3/apps/:guid/processes/:type/stats
Permitted Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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" }'
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
}
},
"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 | The command is used to start the process. |
| health_check | health_check object | The health check to perform on the process. |
Permitted Roles
| Space Developer |
| Admin |
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
}
},
"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
| Space Developer |
| Admin |
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
| Space Developer |
| Admin |
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
}
},
"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
}
},
"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. |
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
}
},
"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
}
},
"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. |
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
| Name | Type | Description |
|---|---|---|
| name | string | Name of the space. |
| guid | uuid | Unique identifier for 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. |
| organization (experimental) | to-one relationship | The organization the space is contained in. |
| links | links object | Links to related resources. |
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"
}
}
}
Definition
POST /v3/spaces
Required Parameters
| Name | Type | Description |
|---|---|---|
| name | string | Space name |
| organization | to-one relationship | A relationship to an organization. |
Permitted Roles
| Admin |
| OrgManager |
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"
}
}
},
{
"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"
}
}
}
]
}
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. |
| 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. |
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"
}
}
}
This endpoint retrieves the specified space object.
Definition
GET /v3/spaces/:guid
Permitted Roles
| Admin |
| Space Developer |
| Read-Only Admin |
| Global Auditor |
| Space Manager |
| Space Auditor |
| Org Manager |
Assign an 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 isolatoin 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
| Org Manager |
| Admin |
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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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
| 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. |
| links | links object | Links to related resources. |
Create a task
Example Request
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 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",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"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/:app_guid/tasks
Required Parameters
| Name | Type | Description |
|---|---|---|
| command | string | Command that will be executed |
Optional Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | string | Name of the task. | auto-generated |
| disk_in_mb | integer | Amount of disk to allocate for the task in MB. | operator-configured default_app_disk_in_mb |
| memory_in_mb | 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 |
Allowed Roles
| Space Developer |
| Admin |
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",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"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
Allowed Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"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/:task_guid/actions/cancel
PUT /v3/tasks/:task_guid/cancel (Deprecated)
Allowed Roles
| Space Developer |
| Admin |
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",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"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",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"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. |
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",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"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",
"created_at": "2016-05-04T17:00:41Z",
"updated_at": "2016-05-04T17:00:42Z",
"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. |
Experimental Resources
App Features
The app feature object
| 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. |
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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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. |
Allowed Roles
| Space Developer |
| Admin |
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
}
],
"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
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": "cflinuxfs2"
}
},
"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"
},
"route_mappings": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
},
"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"
}
}
}
Definition
POST /v3/apps/:guid/actions/restart
Permitted Roles
| Space Developer |
| Admin |
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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
Route Mappings
Route Mappings are relations between an app and a route; to direct traffic from a route to an app, you must first create a mapping.
The route_mapping object
| Name | Type | Description |
|---|---|---|
| guid | uuid | Unique identifier for the route mapping. |
| 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 route mapping
Example Request
curl "https://api.example.org/v3/route_mappings" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"relationships": {
"app": {
"guid": "[app-guid]"
},
"route": {
"guid": "[route_guid]"
}
}
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"created_at": "2016-02-17T01:50:05Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"route": {
"href": "https://api.example.org/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
},
"process": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
}
}
}
Definition
POST /v3/route_mappings
Required Parameters
| Name | Type | Description |
|---|---|---|
| app | to-one relationship | A relationship to an app. |
| route | to-one relationship | A relationship to a route. |
Optional Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| process | to-one relationship | A relationship to a process. This relationship is specified by type instead of guid. |
Permitted Roles
| Space Developer |
| Admin |
Get a route mapping
Example Request
curl "https://api.example.org/v3/route_mappings/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"created_at": "2016-02-17T01:50:05Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"route": {
"href": "https://api.example.org/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
},
"process": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
}
}
}
Definition
GET /v3/route_mappings/:guid
Permitted Roles
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
Delete a route mapping
Example Request
curl "https://api.example.org/v3/route_mappings/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
Definition
DELETE /v3/route_mappings/:guid
Permitted Roles
| Space Developer |
| Admin |
List route mappings
Example Request
curl "https://api.example.org/v3/route_mappings" \
-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/route_mappings?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/route_mappings?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/route_mappings?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"created_at": "2016-02-17T01:50:05Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"route": {
"href": "https://api.example.org/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
},
"process": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
}
}
},
{
"guid": "9f4970a8-9e6f-4984-b0a5-5e4a8af91665",
"created_at": "2016-02-17T01:50:05Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/route_mappings/9f4970a8-9e6f-4984-b0a5-5e4a8af91665"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"route": {
"href": "https://api.example.org/v2/routes/a32332f0-fb30-4e9e-9b78-348b8b6b98b6"
},
"process": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/admin-web"
}
}
}
]
}
Retrieve all route mappings the user has access to.
Definition
GET /v3/route_mappings
Query Parameters
| Name | Type | Description |
|---|---|---|
| app_guids | list of strings | Comma-delimited list of app guids to filter by. |
| route_guids | list of strings | Comma-delimited list of route 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. |
List route mappings for an app
Example Request
curl "https://api.example.org/v3/apps/[guid]/route_mappings" \
-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/route_mappings?page=1&per_page=2"
},
"last": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/route_mappings?page=2&per_page=2"
},
"next": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/route_mappings?page=2&per_page=2"
},
"previous": null
},
"resources": [
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"created_at": "2016-02-17T01:50:05Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"route": {
"href": "https://api.example.org/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
},
"process": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
}
}
},
{
"guid": "9f4970a8-9e6f-4984-b0a5-5e4a8af91665",
"created_at": "2016-02-17T01:50:05Z",
"updated_at": "2016-06-08T16:41:26Z",
"links": {
"self": {
"href": "https://api.example.org/v3/route_mappings/9f4970a8-9e6f-4984-b0a5-5e4a8af91665"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"route": {
"href": "https://api.example.org/v2/routes/a32332f0-fb30-4e9e-9b78-348b8b6b98b6"
},
"process": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/admin-web"
}
}
}
]
}
Retrieve route mappings for an app.
Definition
GET /v3/apps/:guid/route_mappings
Query Parameters
| Name | Type | Description |
|---|---|---|
| route_guids | list of strings | Comma-delimited list of route 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. |
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
| 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. |
| app | to-one relationship | A relationship to an app. |
| 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
| Space Developer |
| Admin |
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
| Space Developer |
| Space Manager |
| Space Auditor |
| Org Manager |
| Admin |
| Admin Read-Only |
| Global Auditor |
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
| Space Developer |
| Admin |
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. |
Service Instances
An instantiation of a service offering.
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"
},
"related": {
"href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/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
| Space Developer |
| Admin |
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
| Space Developer |
| Admin |