Introduction
Overview
Welcome to the Cloud Foundry V3 API docs! Version 3 will add support for several key features:
- GA - Running one-off tasks on Cloud Foundry
- Experimental - Applications consisting of several processes via a Procfile
- Experimental - Direct access to application packages and droplets
More Resources
- The Cloud Foundry V2 API is still the primary API for interacting with Cloud Foundry.
- Running Tasks
- CAPI Slack Channel
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.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 |
---|---|
SpaceManager | This role provides Space management access |
SpaceDeveloper | This role allows developers to create and manage apps and services in a Space |
SpaceAuditor | This role allows 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. |
Resources
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.
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"
}
}
}
-
guid string
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 link 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
-
href string
The absolute URL.
-
method string
An optional field containing the HTTP method to be used when following the URL.
Relationships
Relationships allow users to create, read, update, and delete associations between resources. Relationships are managed through a 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.
To-One relationships
Some relationships relate a resource to exactly one other resource. For example an app can belong to only one space.
Setting the relationship while creating an object
curl "https://api.example.org/v3/books" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"color": "yellow",
"relationships": {
"publisher": {
"guid": "publisher-guid"
}
}
}'
To-Many relationships
Some relationships relate an resource to several other resources. For example an Isolation Segment can be entitled to multiple organizations.
Adding related resources
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"data": [
{ "guid":"author-guid-1" },
{ "guid":"author-guid-2" }
]
}'
Replacing all relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
-X PATCH \
-H "Authorization: bearer [token]" \
-d '{
"data": [
{ "guid":"author-guid-3" },
{ "guid":"author-guid-4" }
]
}'
Removing all relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
-X PATCH \
-H "Authorization: bearer [token]" \
-d '{ "data": [] }'
Removing specific relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
-X DELETE \
-H "Authorization: bearer [token]" \
-d '{ "data": [ { "guid":"author-guid-3" } ] }'
}'
Errors
The error object
An error response will always return a list of error objects in the errors
field.
Example Error
HTTP/1.1 422 Unprocessable
{
"errors": [
{
"code": 10008,
"title": "CF-UnprocessableEntity",
"detail": "The request is semantically invalid: something went wrong"
}
]
}
-
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"
}
}
}
]
}
-
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
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
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
-
guid string
Unique GUID for the task
-
sequence_id integer
User-facing id of the task. This number is unique for every task associated with a given app.
-
name string
User-facing 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 string
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.
-
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 object
Links to related resources.
Create a task
Definition
POST /v3/apps/:guid/tasks HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/tasks" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{ "command": "rake db:migrate" }'
Example Response
HTTP/1.1 202 Accepted
{
"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"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
This endpoint creates a new task.
Body Parameters
-
command required
Command that will be executed
-
name optional
User-facing name of the task
-
memory_in_mb optional
Amount of memory to allocate for the task in MB. Defaults to operater-configurable ‘default_app_memory’ when not specified.
-
disk_in_mb optional
Amount of disk to allocate for the task in MB. Defaults to operater-configurable 'default_app_disk_in_mb’ when not specified.
-
droplet_guid optional
The guid of the droplet that will be used to run the command. Defaults to the app’s current droplet when not specified.
Get a task
Definition
GET /v3/tasks/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/tasks/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
This endpoint retrieves a specific task. The command
field may be excluded
in the response based on the user’s role.
Body Parameters
No arguments
Cancel a task
Definition
PUT /v3/tasks/:task_guid/cancel HTTP/1.1
Example Request
curl "https://api.example.org/v3/tasks/[guid]/cancel" \
-X PUT \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
{
"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"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
}
This endpoint 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.
Body Parameters
No arguments
List tasks
Definition
GET /v3/tasks HTTP/1.1
Example Request
curl "https://api.example.org/v3/tasks" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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"
},
"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"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
},
]
}
This endpoint retrieves the tasks the user has access to. The command
field is excluded in the response.
Query Parameters
-
app_guids optional string
Comma-delimited list of app guids to filter by.
Example:app_guids=app_guid1,app_guid2
-
names optional string
Comma-delimited list of task names to filter by.
-
guids optional string
Comma-delimited list of task guids to filter by.
-
organization_guids optional string
Comma-delimited list of organization guids to filter by.
Example:organization_guids=organization_guid1,organization_guid2
-
space_guids optional string
Comma-delimited list of space guids to filter by.
Example:space_guids=space_guid1,space_guid2
-
states optional string
Comma-delimited list of task states to filter by.
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
List tasks for an app
Definition
GET /v3/apps/:guid/tasks HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/:guid/tasks" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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"
},
"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"
},
"droplet": {
"href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
}
}
},
]
}
This endpoint retrieves the tasks the user has access to. The command
field may be
excluded in the response based on the user’s role.
Query Parameters
-
guids optional string
Comma-delimited list of task guids to filter by.
-
names optional string
Comma-delimited list of task names to filter by.
-
sequence_ids optional integer
Comma delimited list of sequence ids to filter by. Possible values are integers >= 1
-
states optional string
Comma delimited list of task states to filter by.
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
Experimental 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
-
guid string
Unique GUID for the app.
-
name string
An arbitrary name of the app.
-
desired_state string
Current desired state of the app. Can either be
STOPPED
orSTARTED
. -
total_desired_instances integer
Number of desired instances of the application.
-
lifecycle object
Provides the lifecycle object for the application.
-
environment_variables object
Provides the list of custom environment variables available to the application.
-
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 object
Links to related resources.
Create an app
Definition
POST /v3/apps HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"name": "my_app",
"environment_variables": {
"HTTP_PROXY": "http://proxy.example.com"
},
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "java_buildpack"
}
},
"relationships": {
"space": {
"guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
}
}
}'
Example Response
HTTP/1.1 201 Created
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"desired_state": "STOPPED",
"total_desired_instances": 0,
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-06-08T16:41:26Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "java_buildpack",
"stack": "cflinuxfs2"
}
},
"environment_variables": {
"HTTP_PROXY": "http://proxy.example.com"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v2/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"
},
"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/start",
"method": "PUT"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
"method": "PUT"
}
}
}
This endpoint creates a new app.
Body Parameters
-
name required
Name of the App
-
relationships[space][guid] required
Guid for a particular space
-
environment_variables optional
Environment variables to be used for the App when running.
-
lifecycle optional
Lifecycle to be used when creating the app. Note: If no lifecycle is provided, lifecycle type defaults to buildpack. Data is a required field in lifecycle.
Get an app
Definition
GET /v3/apps/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"desired_state": "STOPPED",
"total_desired_instances": 0,
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-06-08T16:41:26Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "java_buildpack",
"stack": "cflinuxfs2"
}
},
"environment_variables": {
"HTTP_PROXY": "http://proxy.example.com"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v2/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"
},
"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/start",
"method": "PUT"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
"method": "PUT"
}
}
}
This endpoint retrieves an app.
Get environment for an app
Definition
GET /v3/apps/:guid/env HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/env" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"staging_env_json": {
"GEM_CACHE": "http://gem-cache.example.com"
},
"running_env_json": {
"HTTP_PROXY": "http://proxy.example.com"
},
"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.com/drain",
"provider": null
}
]
}
},
"application_env_json": {
"VCAP_APPLICATION": {
"limits": {
"fds": 16384
},
"application_name": "my_app",
"application_uris": [ "my_app.example.com" ],
"name": "my_app",
"space_name": "my_space",
"space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
"uris": [ "my_app.example.com" ],
"users": null
}
}
}
This endpoint retrieves the environment variables that will be provided to an app at runtime. It will include environment variables for Environment Variable Groups and Service Bindings.
Update an app
Definition
PATCH /v3/apps/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-d '{
"name": "my_app",
"environment_variables": {
"HTTP_PROXY": "http://proxy.example.com"
},
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "java_buildpack",
}
}
}'
Example Response
HTTP/1.1 200 OK
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"desired_state": "STARTED",
"total_desired_instances": 3,
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "java_buildpack",
"stack": "cflinuxfs2"
}
},
"environment_variables": {
"HTTP_PROXY": "http://proxy.example.com"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v2/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"
},
"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/start",
"method": "PUT"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
"method": "PUT"
}
}
}
This endpoint updates an app.
Body Parameters
-
name optional
Name of the App.
-
environment_variables optional
Environment variables to be used for the App when running.
-
lifecycle optional
Lifecycle to be used when updating the app. Note: If no lifecycle is provided, lifecycle type defaults to buildpack. Data is a required field in lifecycle.
Set current droplet for an app
Definition
PUT /v3/apps/:guid/droplets/current HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/droplets/current" \
-X PUT \
-H "Authorization: bearer [token]" \
-d '{ "droplet_guid": "[droplet_guid]" }'
Example Response
HTTP/1.1 200 OK
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": null,
"stack": null
}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": {
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"hash": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpack": {
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14"
},
"stack": "cflinuxfs2"
},
"environment_variables": {
"CF_STACK": "cflinuxfs2",
"VCAP_APPLICATION": {
"limits": {
"mem": 1024,
"disk": 4096,
"fds": 16384
},
"application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
"application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
"application_name": "my_app",
"application_uris": [
"my_app.example.com"
],
"version": "d5985d64-c455-44d0-99a5-285b6521f84c",
"name": "my_app",
"space_name": "my_space",
"space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
"uris": [
"my_app.example.com"
],
"users": null
},
"MEMORY_LIMIT": "1024m",
"VCAP_SERVICES": {}
},
"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/droplets/current",
"method": "PUT"
}
}
}
This endpoint sets the current droplet for an app. The current droplet is the droplet that the app will use when running.
Get current droplet for an app
Definition
GET /v3/apps/:guid/droplets/current HTTP/1.1
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
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": null,
"stack": null
}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": {
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"hash": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpack": {
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14"
},
"stack": "cflinuxfs2"
},
"environment_variables": {
"CF_STACK": "cflinuxfs2",
"VCAP_APPLICATION": {
"limits": {
"mem": 1024,
"disk": 4096,
"fds": 16384
},
"application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
"application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
"application_name": "my_app",
"application_uris": [
"my_app.example.com"
],
"version": "d5985d64-c455-44d0-99a5-285b6521f84c",
"name": "my_app",
"space_name": "my_space",
"space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
"uris": [
"my_app.example.com"
],
"users": null
},
"MEMORY_LIMIT": "1024m",
"VCAP_SERVICES": {}
},
"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/droplets/current",
"method": "PUT"
}
}
}
This endpoint retrieves the current droplet for an app.
Body Parameters
No arguments
Start an app
Definition
PUT /v3/apps/:guid/start HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/start" \
-X PUT \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"desired_state": "STARTED",
"total_desired_instances": 3,
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "java_buildpack",
"stack": "cflinuxfs2"
}
},
"environment_variables": {
"HTTP_PROXY": "http://proxy.example.com"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v2/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"
},
"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/start",
"method": "PUT"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
"method": "PUT"
}
}
}
This endpoint starts running the app.
Stop an app
Definition
PUT /v3/apps/:guid/stop HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/stop" \
-X PUT \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
"name": "my_app",
"desired_state": "STOPPED",
"total_desired_instances": 3,
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "java_buildpack",
"stack": "cflinuxfs2"
}
},
"environment_variables": {
"HTTP_PROXY": "http://proxy.example.com"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v2/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"
},
"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/start",
"method": "PUT"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
"method": "PUT"
}
}
}
This endpoint stops a running app.
Delete an app
Definition
DELETE /v3/apps/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
This endpoint deletes an app.
List apps
Definition
GET /v3/apps HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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",
"desired_state": "STARTED",
"total_desired_instances": 3,
"created_at": "2016-03-17T21:41:30Z",
"updated_at": "2016-03-18T11:32:30Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "java_buildpack",
"stack": "cflinuxfs2"
}
},
"environment_variables": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
},
"space": {
"href": "https://api.example.org/v2/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"
},
"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/start",
"method": "PUT"
},
"stop": {
"href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
"method": "PUT"
}
}
},
{
"guid": "02b4ec9b-94c7-4468-9c23-4e906191a0f8",
"name": "my_app2",
"desired_state": "STOPPED",
"total_desired_instances": 0,
"created_at": "1970-01-01T00:00:02Z",
"updated_at": "2016-06-08T16:41:26Z",
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "ruby_buildpack",
"stack": "cflinuxfs2"
}
},
"environment_variables": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"links": {
"self": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
},
"space": {
"href": "https://api.example.org/v2/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"
},
"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/start",
"method": "PUT"
},
"stop": {
"href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/stop",
"method": "PUT"
}
}
}
]
}
This endpoint retrieves all the apps the user has access to.
Query Parameters
-
guids optional string
Comma-delimited list of app guids to filter by.
Example:guids=guid1,guid2
-
names optional array of strings
Comma-delimited list of app names to filter by.
Example:names=name1,name2
-
organization_guids optional string
Comma-delimited list of organization guids to filter by.
Example:organization_guids=organization_guid1,organization_guid2
-
space_guids optional string
Comma-delimited list of space guids to filter by.
Example:space_guids=space_guid1,space_guid2
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
Droplets
Droplets are created by 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 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
-
guid string
Unique GUID for the droplet.
-
state string
State of the droplet. Possible states are “STAGING”, “STAGED”, “COPYING”, “FAILED”, or “EXPIRED”.
-
error string
A string describing the last error during the droplet lifecycle.
-
lifecycle object
An object describing the lifecycle that was configured or discovered.
-
staging_memory_in_mb integer
The maximum memory in mb that can be used by a droplet.
-
staging_disk_in_mb integer
The disk quota applied during droplet staging.
-
result object
An object describing the result of a droplet that has completed staging (where state is “STAGED”, “FAILED”, or “EXPIRED”). Droplets in uncomplete states return null result.
-
environment_variables object
Environment variables to be used when staging the droplet. Variables in the
CF_
andVCAP_
scopes will be populated by the system. -
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 object
Links to related resources.
The lifecycle object
Lifecycle objects describe buildpacks or docker images.
Lifecycle object for buildpack droplets
-
type string
“buildpack”
-
data[‘buildpack’] string
The name of the buildpack or a URL from which it may be downloaded, or null to auto-detect the buildpack
-
data['stack’] string
The root filesystem to use with the buildpack, for example “cflinuxfs2”
Lifecycle object for docker
Droplets created with a docker lifecycle are only valid for docker packages.
-
type string
“docker”
-
data string
An empty object should be passed: “{}”
Create a droplet
Definition
POST /v3/packages/:guid/droplets HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages/[guid]/droplets" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"environment_variables": {
"CUSTOM_ENV_VAR": "hello"
},
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": "http://github.com/myorg/awesome-buildpack",
"stack": "cflinuxfs2"
}
}
}'
Example Response
HTTP/1.1 201 Created
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGING",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": null,
"stack": null
}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": null,
"environment_variables": {
"CF_STACK": "cflinuxfs2",
"VCAP_APPLICATION": {
"limits": {
"mem": 1024,
"disk": 4096,
"fds": 16384
},
"application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
"application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
"application_name": "my_app",
"application_uris": [
"my_app.example.com"
],
"version": "d5985d64-c455-44d0-99a5-285b6521f84c",
"name": "my_app",
"space_name": "my_space",
"space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
"uris": [
"my_app.example.com"
],
"users": null
},
"MEMORY_LIMIT": "1024m",
"VCAP_SERVICES": {}
},
"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/droplets/current",
"method": "PUT"
}
}
}
This endpoint creates a new droplet from a package.
Body Parameters
-
environment_variables optional
Environment variables ot use during staging. Environment variable names may not start with
VCAP_
orCF_
.PORT
is not a valid environment variable. -
staging_memory_in_mb optional
Memory limit used to stage package
-
staging_disk_in_mb optional
Disk limit used to stage package
-
lifecycle optional
Lifecycle information for a droplet. If not provided, it will default to what is specified on the app. If the app does not have lifecycle information, it will default to a buildpack.
Copy a droplet
Definition
POST /v3/droplets/:guid/copy HTTP/1.1
Example Request
curl "https://api.example.org/v3/droplets/[guid]/copy" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"relationships": {
"app": {
"guid": "[app-guid]"
}
}
}'
Example Response
HTTP/1.1 201 Created
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "COPYING",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": null,
"stack": null
}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": null,
"environment_variables": {},
"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/droplets/current",
"method": "PUT"
}
}
}
This endpoint copies a droplet to a different app. The copied droplet excludes the environment variables listed on the source droplet.
Query Parameters
-
guid optional
Source guid of the droplet to be copied
Get a droplet
Definition
GET /v3/droplets/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/droplets/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
"state": "STAGED",
"error": null,
"lifecycle": {
"type": "buildpack",
"data": {
"buildpack": null,
"stack": null
}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": {
"execution_metadata": "",
"process_types": {
"rake": "bundle exec rake",
"web": "bundle exec rackup config.ru -p $PORT"
},
"hash": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpack": {
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14"
},
"stack": "cflinuxfs2"
},
"environment_variables": {
"CF_STACK": "cflinuxfs2",
"VCAP_APPLICATION": {
"limits": {
"mem": 1024,
"disk": 4096,
"fds": 16384
},
"application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
"application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
"application_name": "my_app",
"application_uris": [
"my_app.example.com"
],
"version": "d5985d64-c455-44d0-99a5-285b6521f84c",
"name": "my_app",
"space_name": "my_space",
"space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
"uris": [
"my_app.example.com"
],
"users": null
},
"MEMORY_LIMIT": "1024m",
"VCAP_SERVICES": {}
},
"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/droplets/current",
"method": "PUT"
}
}
}
This endpoint retrieves a specific droplet.
Body Parameters
No arguments
Delete a droplet
Definition
DELETE /v3/droplets/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/droplets/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
This endpoint deletes a specific droplet.
Body Parameters
No arguments
List droplets
Definition
GET /v3/droplets HTTP/1.1
Example Request
curl "https://api.example.org/v3/droplets" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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": {
"buildpack": null,
"stack": null
}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": {
"execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"hash": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpack": {
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14"
},
"stack": "cflinuxfs2"
},
"environment_variables": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"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/droplets/current",
"method": "PUT"
}
}
},
{
"guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
"state": "STAGING",
"error": null,
"lifecycle": {
"type": "docker",
"data": {}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": null,
"environment_variables": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"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/droplets/current",
"method": "PUT"
}
}
}
]
}
This endpoint retrieves the droplets the user has access to.
Query Parameters
-
app_guids optional string
Comma-delimited list of app guids to filter by.
Example:app_guids=app_guid1,app_guid2
-
guids optional string
Comma-delimited list of droplet guids to filter by.
Example:guids=guid1,guid2
-
organization_guids optional string
Comma-delimited list of organization guids to filter by.
Example:organization_guids=organization_guid1,organization_guid2
-
space_guids optional string
Comma-delimited list of space guids to filter by.
Example:space_guids=space_guid1,space_guid2
-
states optional string
Comma-delimited list of droplet states to filter by.
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
List droplets for an app
Definition
GET /v3/apps/:guid/droplets HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/droplets" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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": {
"buildpack": null,
"stack": null
}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": {
"execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"hash": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpack": {
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14"
},
"stack": "cflinuxfs2"
},
"environment_variables": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"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/droplets/current",
"method": "PUT"
}
}
},
{
"guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
"state": "STAGING",
"error": null,
"lifecycle": {
"type": "docker",
"data": {}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": null,
"environment_variables": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"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/droplets/current",
"method": "PUT"
}
}
}
]
}
This endpoint retrieves a list of droplets belonging to an app.
Body Parameters
-
guids optional string
Comma-delimited list of droplet guids to filter by.
Example:guids=guid1,guid2
-
page optional
Page to display. Possible values are all integers >= 1.
-
states optional
Comma-delimited list of droplet states to filter by.
Example:states=STAGING
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
List droplets for a package
Definition
GET /v3/packages/:guid/droplets HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages/[guid]/droplets" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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": {
"buildpack": null,
"stack": null
}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": {
"execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
"process_types": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"hash": {
"type": "sha256",
"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"buildpack": {
"name": "ruby_buildpack",
"detect_output": "ruby 1.6.14"
},
"stack": "cflinuxfs2"
},
"environment_variables": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"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/droplets/current",
"method": "PUT"
}
}
},
{
"guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
"state": "STAGING",
"error": null,
"lifecycle": {
"type": "docker",
"data": {}
},
"staging_memory_in_mb": 1024,
"staging_disk_in_mb": 4096,
"result": null,
"environment_variables": {
"redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
},
"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/droplets/current",
"method": "PUT"
}
}
}
]
}
This endpoint retrieves a list of droplets belonging to a package.
Body Parameters
-
guids optional string
Comma-delimited list of droplet guids to filter by.
Example:guids=guid1,guid2
-
page optional
Page to display. Possible values are all integers >= 1.
-
states optional
Comma-delimited list of droplet states to filter by.
Example:states=STAGING
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
Isolation Segments
Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.
The isolation_segment object
-
guid string
Unique GUID for the isolation_segment.
-
name string
An arbitrary name of 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 object
Links to related resources.
Create an isolation segment
Definition
POST /v3/isolation_segments HTTP/1.1
Example Request
curl "https://api.example.org/v3/isolation_segments" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"name": "my_segment"
}'
Example Response
HTTP/1.1 201 Created
{
"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"
},
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
}
}
}
This endpoint creates a new isolation segment. Only Admins can create isolation segments.
Body Parameters
-
name required
Name of the Isolation Segment. Isolation Segment names must be unique across the entire system, and case is ignored when checking for uniqueness.
Get an isolation segment
Definition
GET /v3/isolation_segments/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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"
},
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
}
}
}
This endpoint retrieves an isolation segment.
Update an isolation segment
Definition
PUT /v3/isolation_segments/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
-X PUT \
-H "Authorization: bearer [token]" \
-d '{
"name": "my_isolation_segment"
}'
Example Response
HTTP/1.1 200 OK
{
"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"
},
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
}
}
}
This endpoint updates an isolation_segment. Only Admins can update isolation segments.
Body Parameters
-
name
Name of the Isolation Segment. The name must be unique across the entire system, and case is ignored when checking for uniqueness.
Delete an isolation segment
Definition
DELETE /v3/isolation_segments/:guid HTTP/1.1
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
This endpoint deletes an isolation segment. An isolation segment cannot be deleted if it is still in the allowed list for any organization. Only Admins can delete isolation segments.
List isolation segments
Definition
GET /v3/isolation_segments HTTP/1.1
Example Request
curl "https://api.example.org/v3/isolation_segments" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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"
},
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/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"
},
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac/relationships/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"
},
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03/relationships/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"
},
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0/relationships/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": {
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7/relationships/organizations"
}
}
}
]
}
This endpoint retrieves all the 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.
Query Parameters
-
guids optional string
Comma-delimited list of isolation_segment guids to filter by.
Example:guids=guid1,guid2
-
names optional array of strings
Comma-delimited list of isolation segment names to filter by.
Example:names=name1,name2
-
organization_guids optional string
Comma-delimited list of organization guids to filter by.
Example:organization_guids=organization_guid1,organization_guid2
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
Entitle one or more organizations for an isolation segment
Definition
POST /v3/isolation_segments/:guid/relationships/organizations HTTP/1.1
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"data": [
{ "guid":"org-guid-1" },
{ "guid":"org-guid-2" }
]
}'
Example Response
HTTP/1.1 201 OK
{
"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"
},
"spaces": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
},
"organizations": {
"href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
}
}
}
This endpoint entitles the specified organizations for the isolation segment. Only Admins can entitle organizations for isolation segments. 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.
Body Parameters
-
data
Array of organizations, each specified by its guid, to be entitled.
Revoke entitlement to isolation segment for one or more organizations
Definition
DELETE /v3/isolation_segments/:guid/relationships/organizations HTTP/1.1
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
-X DELETE \
-H "Authorization: bearer [token]" \
-d '{
"data": [
{ "guid":"org-guid-1" },
{ "guid":"org-guid-2" }
]
}'
Example Response
HTTP/1.1 204 No Content
This endpoint revokes the entitlements for the specified organizations to the isolation segment. Only Admins can revoke isolation segment entitlements. 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, and the organization has more than one isolation segment, the entitlement cannot be revoked.
Body Parameters
-
data
Array of organizations, each specified by its guid, for which entitlement will be revoked.
List organizations for an isolation segment
Definition
GET /v3/isolation_segments/:guid/relationships/organizations HTTP/1.1
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
{
"data": [
{
"name": "org1",
"guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac",
"link": "/v2/organizations/68d54d31-9b3a-463b-ba94-e8e4c32edbac"
},
{
"name": "org2",
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
"link": "/v2/organizations/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
}
]
}
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.
List spaces for an isolation segment
Definition
GET /v3/isolation_segments/:guid/relationships/spaces HTTP/1.1
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
{
"data": [
{
"name": "space1",
"guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac",
"link": "/v2/spaces/68d54d31-9b3a-463b-ba94-e8e4c32edbac"
},
{
"name": "space2",
"guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
"link": "/v2/spaces/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
}
]
}
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.
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
-
guid string
Unique GUID for the package.
-
type string
Package type. Possible values are “bits”, “docker”.
-
data object
Data for docker packages. Can be empty for bits packages.
-
state string
State of the package. Possible states are “PROCESSING_UPLOAD”, “READY”, “FAILED”, “AWAITING_UPLOAD”, “COPYING”, and “EXPIRED”.
-
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 object
Links to related resources.
Create a package
Definition
POST /v3/apps/:guid/packages HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/packages" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"type": "docker",
"data": {
"image": "registry/image:latest"
}
}'
Example Response
HTTP/1.1 201 Created
{
"guid": "4cb65058-f04f-458f-aca1-5f4e43de6407",
"type": "docker",
"data": {
"hash": {
"type": "sha256",
"value": null
},
"error": null,
"image": "registry/image:latest"
},
"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"
}
}
}
This endpoint creates a new package.
Body Parameters
-
type required
Package type. Possible values are “bits”, “docker”.
-
data optional
Data for docker packages. Can be empty for bits packages.
-
data[‘image’] optional
Location of docker image. Required for docker packages.
Get a package
Definition
GET /v3/packages/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
"type": "bits",
"data": {
"hash": {
"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"
},
"stage": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/droplets",
"method": "POST"
},
"app": {
"href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
}
}
This endpoint retrieves a specific package.
Body Parameters
No arguments
Stage a package
Staging a package is accomplished by creating a droplet. See Create a droplet
Upload package bits
Definition
POST /v3/packages/:guid/upload HTTP/1.1
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
{
"guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
"type": "bits",
"data": {
"hash": {
"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"
},
"stage": {
"href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/droplets",
"method": "POST"
},
"app": {
"href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
}
}
}
This endpoint uploads bits to an existing package of type ‘bits’. The bits must be sent as part of a multi-part form
Form Parameters
-
bits required
A binary zip file containing the package bits
Download package bits
Definition
GET /v3/packages/:guid/download HTTP/1.1
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.
Body Parameters
No arguments
Copy a Package
Definition
POST /v3/apps/:guid/packages HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/packages?source_package_guid=[guid]" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 201 Created
{
"guid": "fec72fc1-e453-4463-a86d-5df426f337a3",
"type": "docker",
"data": {
"image": "http://awesome-sauce.com"
},
"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/fec72fc1-e453-4463-a86d-5df426f337a3"
},
"stage": {
"href": "https://api.example.org/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3/droplets",
"method": "POST"
},
"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.
Query Parameters
-
source_package_guid required
Source of package to copy from
Delete a package
Definition
DELETE /v3/packages/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages/[guid]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
This endpoint deletes a specific package.
Body Parameters
No arguments
List packages
Definition
GET /v3/packages HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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": {
"hash": {
"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"
},
"stage": {
"href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/droplets",
"method": "POST"
},
"app": {
"href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
}
}
},
{
"guid": "8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691",
"type": "docker",
"data": {
"hash": {
"type": "sha256",
"value": null
},
"error": null,
"image": "repository/docker-image:latest"
},
"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"
}
}
}
]
}
This endpoint retrieves all the packages the user has access to.
Query Parameters
-
app_guids optional string
Comma-delimited list of app guids to filter by.
Example:app_guids=app_guid1,app_guid2
-
guids optional string
Comma-delimited list of package guids to filter by.
Example:guids=guid1,guid2
-
organization_guids optional string
Comma-delimited list of organization guids to filter by.
Example:organization_guids=organization_guid1,organization_guid2
-
space_guids optional string
Comma-delimited list of space guids to filter by.
Example:space_guids=space_guid1,space_guid2
-
states optional string
Comma-delimited list of package states to filter by.
-
types optional string
Comma-delimited list of package types to filter by.
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
List packages for an app
Definition
GET /v3/apps/:guid/packages HTTP/1.1
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,
"hash": {
"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"
},
"stage": {
"href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/droplets",
"method": "POST"
},
"app": {
"href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69"
}
}
}
]
}
This endpoint retrieves the packages that associates with the given app guid.
Query Parameters
-
guids optional string
Comma-delimited list of package guids to filter by.
Example:guids=guid1,guid2
-
states optional string
Comma-delimited list of package states to filter by.
-
types optional string
Comma-delimited list of package types to filter by.
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
Processes By Guid
Processes define the runnable units of an app. An app can have multiple process types, each with differing commands and scale.
To configure processes for an app, a Procfile should be provided in the application source.
The process object
-
guid string
Unique GUID for the process.
-
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.
-
ports array of integers
The ports that will be open to accept traffic in the container running the process. An empty array will bind no ports to the application.
web
type processes will default to using port 8080 when ports are not provided. All other process types will default to no ports. -
health_check health_check object
The health check to perform on the process. See health_check for more information.
-
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 object
Links to related resources.
The health_check object
-
type string
The type of health check to perform. Valid values are
port
andprocess
-
data[‘timeout’] integer
The time in seconds that the health check can fail before the process is restarted.
The process stats object
-
type string
Process type. A unique identifier for processes belonging to an app.
-
index integer
The zero-based index of running intances.
-
state string
The state of the instance. RUNNING, CRASHED, STARTING
-
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
Definition
GET /v3/processes/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
"type": "web",
"command": "rackup",
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"ports": [8080],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
}
}
}
This endpoint retrieves a specific process.
Body Parameters
No arguments
Get stats for a process
Definition
GET /v3/processes/:guid/stats HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes/[guid]/stats" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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
}
]
}
This endpoint retrieves the stats for a specific process.
Body Parameters
No arguments
Update a process
Definition
PATCH /v3/processes/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes/[guid]" \
-X PATCH \
-H "Authorization: bearer [token]" \
-d '{ "command": "rackup" }'
Example Response
HTTP/1.1 200 OK
{
"guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
"type": "web",
"command": "rackup",
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"ports": [8080],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
}
}
}
This endpoint updates an existing process.
Body Parameters
-
command optional
The command that will be used to start the process.
-
ports optional
The ports that will be open to accept traffic in the container running the process. An empty array will bind no ports to the application.
web
type processes will default to using port 8080 when ports are not provided. All other process types will default to no ports. -
health_check optional
The health check to perform on the process. See health_check for more information.
Scale a process
Definition
PUT /v3/processes/:guid/scale HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes/[guid]/scale" \
-X PUT \
-H "Authorization: bearer [token]" \
-d '{
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
}'
Example Response
HTTP/1.1 202 OK
{
"guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
"type": "web",
"command": "rackup",
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"ports": [8080],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
}
}
}
This endpoint scales an existing process.
Body Parameters
-
instances optional
The number of instances.
-
memory_in_mb optional
The memory in mb allocated per instance.
-
disk_in_mb optional
The disk in mb allocated per instance.
Terminate a process instance
Definition
DELETE /v3/processes/:guid/instances/:index HTTP/1.1
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
This endpoint terminates 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.
Body Parameters
No arguments
List processes
Definition
GET /v3/processes HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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,
"ports": [8080],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/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,
"ports": [],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
}
}
}
]
}
This endpoint retrieves the processes the user has access to.
Query Parameters
-
app_guids optional string
Comma-delimited list of app guids to filter by.
Example:app_guids=app_guid1,app_guid2
-
guids optional string
Comma-delimited list of process guids to filter by.
Example:guids=guid1,guid2
-
organization_guids optional string
Comma-delimited list of organization guids to filter by.
Example:organization_guids=organization_guid1,organization_guid2
-
space_guids optional string
Comma-delimited list of space guids to filter by.
Example:space_guids=space_guid1,space_guid2
-
types optional string
Comma-delimited list of process types to filter by.
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
Processes By App and Type
Processes define the runnable units of an app. An app can have multiple process types, each with differing commands and scale.
To configure processes for an app, a Procfile should be provided in the application source.
The process object
-
guid string
Unique GUID for the process.
-
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.
-
ports array of integers
The ports that will be open to accept traffic in the container running the process. An empty array will bind no ports to the application.
web
type processes will default to using port 8080 when ports are not provided. All other process types will default to no ports. -
health_check health_check object
The health check to perform on the process. See health_check for more information.
-
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 object
Links to related resources.
The health_check object
-
type string
The type of health check to perform. Valid values are
port
andprocess
-
data[‘timeout’] integer
The time in seconds that the health check can fail before the process is restarted.
The process stats object
-
type string
Process type. A unique identifier for processes belonging to an app.
-
index integer
The zero-based index of running intances.
-
state string
The state of the instance. RUNNING, CRASHED, STARTING
-
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 for an app
Definition
GET /v3/apps/:guid/processes/:type HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/processes/[type]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
"type": "web",
"command": "rackup",
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"ports": [8080],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
}
}
}
This endpoint retrieves a specific process belonging to an app.
Body Parameters
No arguments
Get stats for a process for an app
Definition
GET /v3/apps/:guid/processes/:type/stats HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/processes/[type]/stats" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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
}
]
}
This endpoint retrieves the stats for a specific process belonging to an app.
Body Parameters
No arguments
Scale a process for an app
Definition
PUT /v3/apps/:guid/processes/:type/scale HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/processes/[type]/scale" \
-X PUT \
-H "Authorization: bearer [token]" \
-d '{
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
}'
Example Response
HTTP/1.1 202 OK
{
"guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
"type": "web",
"command": "rackup",
"instances": 5,
"memory_in_mb": 256,
"disk_in_mb": 1024,
"ports": [8080],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
}
}
}
This endpoint scales an existing process belonging to an app.
Body Parameters
-
instances optional
The number of instances.
-
memory_in_mb optional
The memory in mb allocated per instance.
-
disk_in_mb optional
The disk in mb allocated per instance.
Terminate a process instance for an app
Definition
DELETE /v3/apps/:guid/processes/:type/instances/:index HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/processes/[type]/instances/[index]" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content
This endpoint terminates an instance of a specific process belonging to an app. Health management will eventually restart the instance.
This allows a user to stop a single misbehaving instance of a process.
Body Parameters
No arguments
List processes for an app
Definition
GET /v3/apps/:guid/processes HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/processes \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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,
"ports": [8080],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/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,
"ports": [],
"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/scale",
"method": "PUT"
},
"app": {
"href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
},
"space": {
"href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
},
"stats": {
"href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
}
}
}
]
}
This endpoint retrieves the processes belonging to an app.
Query Parameters
-
app_guids optional string
Comma-delimited list of app guids to filter by.
Example:app_guids=app_guid1,app_guid2
-
guids optional string
Comma-delimited list of process guids to filter by.
Example:guids=guid1,guid2
-
organization_guids optional string
Comma-delimited list of organization guids to filter by.
Example:organization_guids=organization_guid1,organization_guid2
-
space_guids optional string
Comma-delimited list of space guids to filter by.
Example:space_guids=space_guid1,space_guid2
-
types optional string
Comma-delimited list of process types to filter by.
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
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
-
guid string
Unique GUID for the route mapping.
-
app_port integer
The port that traffic will be routed to for the mapped 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 object
Links to related resources.
Create a route mapping
Definition
POST /v3/route_mappings HTTP/1.1
Example Request
curl "https://api.example.org/v3/route_mappings" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"relationships": {
"app": {
"guid": "[app-guid]"
},
"route": {
"guid": "[route_guid]"
}
}
}'
Example Response
HTTP/1.1 201 Created
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"app_port": 8080,
"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"
}
}
}
This endpoint creates a new route mapping.
Body Parameters
-
app_port optional
The port that traffic will be routed to for the mapped process. Defaults to
8080
-
relationships[‘app’]['guid’] required
Guid of the app to which you would like to map the route.
-
relationships['route’]['guid’] required
Guid of the route to which you would like to map the app.
-
relationships['process’]['type’] optional
Type of the process on the app to which you would like to map the route. Defaults to
web
Get a route mapping
Definition
GET /v3/route_mappings/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/route_mappings/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
"app_port": 8080,
"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"
}
}
}
This endpoint retrieves a specific route mapping.
Body Parameters
No arguments
Delete a route mapping
Definition
DELETE /v3/route_mappings/:guid HTTP/1.1
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
This endpoint deletes a specific route mapping.
Body Parameters
No arguments
List route mappings
Definition
GET /v3/route_mappings HTTP/1.1
Example Request
curl "https://api.example.org/v3/route_mappings" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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",
"app_port": 8080,
"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",
"app_port": 8080,
"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"
}
}
}
]
}
This endpoint retrieves the route mappings the user has access to.
Query Parameters
-
app_guids optional string
Comma-delimited list of app guids to filter by.
Example:app_guids=app_guid1,app_guid2
-
route_guids optional string
Comma-delimited list of route guids to filter by.
Example:route_guids=route_guid1,route_guid2
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.
List route mappings for an app
Definition
GET /v3/apps/:guid/route_mappings HTTP/1.1
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
{
"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",
"app_port": 8080,
"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",
"app_port": 8080,
"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"
}
}
}
]
}
This endpoint retrieves the route mappings the user has access to.
Query Parameters
route_guids
optional string
Comma-delimited list of route guids to filter by.
Example: route_guids=route_guid1,route_guid2
page
optional
Page to display. Possible values are all integers >= 1.
per_page
optional
Number of results per page. Possible values are 1 through 5000.
order_by
optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values are created_at
or 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
-
guid string
Unique GUID for the service binding
-
type string
Service binding type. Currently only possible value is “app”.
-
data object
Data returned from the service broker for the service instance. Currently possible values are “credentials”, “syslog_drain_url” and (experimental) “volume_mounts”.
-
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 object
Links to related resources.
Create a service binding
Definition
POST /v3/service_bindings HTTP/1.1
Example Request
curl "https://api.example.org/v3/service_bindings" \
-X POST \
-H "Authorization: bearer [token]" \
-d '{
"type": "app",
"relationships": {
"app": {
"guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
},
"service_instance": {
"guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
},
},
"data": {
"parameters": {
"some_object_id": "for_the_service_broker"
}
}
}'
Example Response
HTTP/1.1 201 Created
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"type": "app",
"data": {
"credentials": {
"super-secret": "password"
},
"syslog_drain_url": "syslog://drain.url.com",
"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"
}
}
}
This endpoint creates a new service binding.
Body Parameters
-
type required
Service binding type. Currently, the only possible value is “app”.
-
relationships[‘app’]['guid’] required
Guid of the app to which you would like to bind the service instance.
-
relationships['service_instance’]['guid’] required
Guid of the service instance to which you would like to bind the app.
-
data['parameters’] optional
Additional configuration parameters for the service binding.
Get a service binding
Definition
GET /v3/service_bindings/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/service_bindings/[guid]" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
"type": "app",
"data": {
"credentials": {
"super-secret": "password"
},
"syslog_drain_url": "syslog://drain.url.com",
"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"
}
}
}
This endpoint retrieves a specific service binding.
Body Parameters
No arguments
Delete a service binding
Definition
DELETE /v3/service_bindings/:guid HTTP/1.1
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
This endpoint deletes a specific service binding.
Body Parameters
No arguments
List service bindings
Definition
GET /v3/service_bindings HTTP/1.1
Example Request
curl "https://api.example.org/v3/service_bindings" \
-X GET \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
"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.com",
"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.com",
"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.
Query Parameters
-
app_guids optional string
Comma-delimited list of app guids to filter by.
Example:app_guids=app_guid1,app_guid2
-
service_instance_guids optional string
Comma-delimited list of service_instance_guids types to filter by. Example:
service_instance_guids=guid1,guid2
-
page optional
Page to display. Possible values are all integers >= 1.
-
per_page optional
Number of results per page. Possible values are 1 through 5000.
-
order_by optional
Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
Possible values arecreated_at
orupdated_at
.