Introduction

Overview

Welcome to the Cloud Foundry V3 API docs! Version 3 will add support for several key features:

• Running one-off tasks on Cloud Foundry
• Applications consisting of several processes via a Procfile
• Direct access to application packages and droplets

Getting help

The CAPI team can most easily be reached from our Slack channel for questions and issues regarding the API. To report an issue with the docs or API, please feel free to file a GitHub issue on our API repo cloud_controller_ng.

We recommend reaching out to slack first as the team will be most responsive there.

More resources

• The Cloud Foundry V2 API is still the primary API for interacting with Cloud Foundry.
• Running Tasks
• V3 API Documentation Source Code

Concepts

API Resource

A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object.

A resource consists of several required resource fields and other attributes specific to the resource.

See Resources and Experimental Resources for specific resources.

Required fields

Example Person Resource

{
  "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
  "created_at": "2016-03-18T23:26:46Z",
  "updated_at": "2016-10-17T20:00:42Z",

  "name": "Bob",

  "links": {
    "self": {
      "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}

Name	Type	Description
guid	uuid	The unique identifier for the resource.
created_at	datetime	The ISO8601 compatible date and time when resource was created.
updated_at	datetime	The ISO8601 compatible date and time when resource was last updated.
links	links object	Provide URLs to related resources and actions for the current resource.

Links

Links provide URLs to relationships and actions for a resource. Links are represented as a JSON object and will always contain at least a self link.

Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET.

The link object

Example Link object

{
  "href": "http://example.com/some/endpoint",
  "method": "GET"
}

Name	Type	Description
href	string	The absolute URL.
method	string	An optional field containing the HTTP method to be used when following the URL.

Authentication

The Cloud Foundry V3 API is secured using OAuth 2. Clients are expected to present a valid bearer token via HTTP header: Authorization: bearer <token>

Tokens can be obtained from the Cloud Foundry UAA server. For more information, see the UAA API Documentation

Authorization

Access to resources is determined by combining scopes in the OAuth2 Token with User Roles that are managed by the API. User Roles are currently managed by the V2 API.

OAuth2 scopes

Scope	Description
cloud_controller.admin	This scope provides read and write access to all resources
cloud_controller.admin_read_only	This scope provides read only access to all resources
cloud_controller.global_auditor	This scope provides read only access to all resources except secrets (such as environment variables)
cloud_controller.read	This scope provides read access to resources based on user roles
cloud_controller.write	This scope provides write access to resources based on user roles

Cloud Foundry user roles

Role	Description
Admin	Allows a user to manage the platform. OAuth token must contain cloud_controller.admin scope.
Admin Read-Only	Allows a user to read all resources on the platform. OAuth token must contain cloud_controller.admin_read_only scope.
Global Auditor	Allows a user to read all resources on the platform, excluding sensitive data such as environment variables and service bindings. OAuth token must contain cloud_controller.global_auditor scope.
Org Member	Allows a user to be assigned other roles within an Organization and its Spaces
Org Manager	Provides Organization management access
Org Auditor	Provides read-only access to a Organization for auditing purposes
Org Billing Manager	Allows a user to create and manage billing account and payment information
Space Developer	Allows developers to create and manage apps and services in a Space
Space Manager	Provides Space management access
Space Auditor	Provides read-only access to a Space for auditing purposes

Errors

Example Error

{
  "errors": [
    {
      "code": 10008,
      "title": "CF-UnprocessableEntity",
      "detail": "something went wrong"
    }
  ]
}

An error response will always return a list of error objects in the errors field.

The error object

Name	Type	Description
code	integer	A numeric code for this error.
title	string	Short description of the error.
detail	string	Detailed description of the error.

Filters

Endpoints that return lists of resources support filtering down the returned resources using query parameters.

Examples

Single value request

GET /v3/apps?names=the_name

This will return all apps with name the_name.

Multiple value request

GET /v3/apps?names=first_name,second_name

This will return all apps with name the_name OR second_name.

Combined filters

GET /v3/apps?names=the_name&state=STARTED

This will return all apps with name the_name AND state STARTED.

Empty filters

An empty filter (/v3/resources?fields=) can mean either empty string ("") or NULL, depending on the resource type.

GET /v3/buildpacks?stacks=

This will return all buildpacks with stack NULL.

GET /v3/routes?paths=pepper,,tabi

This will return all routes with path "pepper", "" OR "tabi".

Include

The include parameter allows clients to fetch resources and ensure that information about the parent object(s) is part of the response. For example, a response to /v3/spaces/:guid?include=org will contain detailed information about the space and its parent org.

Developers may choose to use the include feature to reduce the number of API calls. The include query param can be used with a single resource or a list of resources.

Resources

The following resources can take an include parameter:

Resource	Allowed values
apps	org, space
apps/[:guid]	org, space
spaces	org
spaces/[:guid]	org

Sample requests

Example request to apps resource to include parent orgs and spaces

curl "https://api.example.org/v3/apps?include=org,space" \
  -X GET \
  -H "Authorization: bearer [token]"

Example response

{
   "pagination": {
      "total_results": 2
      // rest of pagination omitted
   },
   "resources": [
      {
         "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
         "name": "app1"
         // rest omitted
      },
      {
         "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
         "name": "app2"
         // rest omitted
      }
   ],
   "included": {
      "spaces": [
         {
            "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
            "name": "space1"
            // rest of info on space1 omitted
         },
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space2"
            // rest of info on space2 omitted
         }
      ],
      "organizations": [
         {
            "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
            "name": "org1"
            // rest of info on org1 omitted
         },
         {
            "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
            "name": "org2"
            // rest of info on org2 omitted
         }
      ]
   }
}

Example request for a single app instance to include its parent space

curl "https://api.example.org/v3/apps/[guid]?include=space" \
  -X GET \
  -H "Authorization: bearer [token]"

Example response

{
   "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
   "name": "staticfile",
   // ...
   "included": {
      "spaces": [
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space1a"
           // ...
         }
      ]
   }
}

Example request for all spaces including their parent orgs

curl "https://api.example.org/v3/spaces?include=org" \
  -X GET \
  -H "Authorization: bearer [token]"

    Example Response

{
   "pagination": {
      "total_results": 4,
      "total_pages": 1,
     // ...
   },
   "resources": [
      {
         "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
         "name": "space"
         // ...
      },
      {
         "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
         "name": "space1a"
        // ...
      },
      {
         "guid": "615e724a-dfae-4846-836b-8c413f6192cd",
         "name": "space1b"
         // ...
      },
      {
         "guid": "5801b8dd-5ca6-41bb-ba23-690e703c631a",
         "name": "space2a"
        // ...
      }
   ],
   "included": {
      "organizations": [
         {
            "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
            "name": "org"
            // ...
         },
         {
            "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
            "name": "org1"
            // ...
         },
         {
            "guid": "c4bf7e09-57e7-453c-8b8e-fbebc986201e",
            "name": "org2"
            // ...
         }
      ]
   }
}

Lifecycles

Lifecycles inform the platform of how to build droplets and run apps. For example the buildpack lifecycle will use a droplet and a rootfs to run the app, while a docker lifecycle will pull a Docker image from a registry to run an app.

The lifecycle object

Name	Type	Description
type	string	Type of the lifecycle. Valid values are buildpack, docker.
data	object	Data that is used during staging and running for a lifecycle.

Buildpack lifecycle

Example Buildpack Lifecycle

{
  "type": "buildpack",
  "data": {
    "buildpacks": ["java_buildpack"],
    "stack": "cflinuxfs3"
  }
}

This is the default lifecycle for Cloud Foundry. When staging an app with this lifecycle, the app source code will be compiled using a buildpack, resulting in a droplet. When running an app with this lifecycle, a container running a rootfs will be created and the droplet will be expanded inside that container to be executed.

Buildpack lifecycle object

Name	Type	Description
type	string	buildpack
data.buildpacks	array of strings	A list of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack.
data.stack	string	The root filesystem to use with the buildpack, for example cflinuxfs3

Docker lifecycle

Example Docker Lifecycle

{
  "type": "docker",
  "data": {}
}

This allows Cloud Foundry to run Docker images. When staging an app with this lifecycle, the Docker registry is queried for metadata about the image, such as ports and start command. When running an app with this lifecycle, a container is created and the Docker image is executed inside of it.

Docker lifecycle object

Name	Type	Description
type	string	docker
data	object	Data is not used by the Docker lifecycle. Valid value is {}.

Metadata

Metadata allows you to tag API Resources with information that does not directly affect its functionality.

Annotations

Example Resource with Annotations

{
  "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
  "created_at": "2016-03-18T23:26:46Z",
  "updated_at": "2016-10-17T20:00:42Z",

  "name": "api-server",

  "metadata": {
    "labels": {},
    "annotations": {
      "contacts": "Bill tel(1111111) email(bill@fixme), Bob tel(222222) pager(3333333#555) email(bob@fixme)"
    }
  },

  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}

Annotations are user-specified key/value pairs that are attached to API Resources. Annotations are not queryable, non-identifying attributes of a resource, and they do not affect the operation of CloudFoundry.

Examples may include (but are not limited to):

• "contact info": "[email protected] [email protected]"
• "library versions": "Spring: 5.1, Redis Client: a184098. yaml parser: 38"
• "git-sha": "d56fe0367554ae5e878e37ed6c5b9a82f5995512"

Annotation key

Annotation keys are made up of an (optional) prefix, and name. If a prefix is present, it is separated from the name by a /. Prefixes are dns names intended to enable namespacing of annotation keys.

A annotation key prefix must adhere to the following restrictions:

• Length: 0-253 characters
• Allowed characters: alphanumeric, -, and .
• DNS subdomain format (series of subdomain annotations separated by .)

A annotation key name must adhere to the following restrictions:

• Length: 1-63 characters
• Allowed characters: alphanumeric , -, _, and .
• Must begin and end with an alphanumeric character

Annotation value

Annotation values must adhere to the following restrictions:

• Length: 0-5000 characters

Labels and selectors

Example Resource with Labels

{
  "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
  "created_at": "2016-03-18T23:26:46Z",
  "updated_at": "2016-10-17T20:00:42Z",

  "name": "api-server",

  "metadata": {
    "labels": {
      "environment": "production",
      "internet-facing": "false"
    },
    "annotations": {}
  },

  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}

Labels are user-specified key/value pairs that are attached to API Resources. They are queryable, identifying attributes of a resource, but they do not affect the operation of CloudFoundry.

For example, an app may be assigned a label with key sensitive and possible values true or false.

Users could then find all sensitive apps with a selector for sensitive=true, resulting in a response containing only apps having the label key sensitive with a label value of false.

Labels

Labels allow users to apply identifying attributes to resources that are meaningful to the user, but not the CloudFoundry system.

Examples may include (but are not limited to):

• "production" : "true" or "production" : "false"
• "env" : "dev" or "env" : "test" or "env" : "prod"
• "chargeback-code" : "abc123"

Label keys

Label keys are made up of an (optional) prefix, and name. If a prefix is present, it is separated from the name by a /. Prefixes are dns names intended to enable namespacing of label keys.

A label key prefix must adhere to the following restrictions:

• Length: 0-253 characters
• Allowed characters: alphanumeric, -, and .
• DNS subdomain format (series of subdomain labels separated by .)

A label key name must adhere to the following restrictions:

• Length: 1-63 characters
• Allowed characters: alphanumeric , -, _, and .
• Must begin and end with an alphanumeric character

Label values

Label values must adhere to the following restrictions:

• Length: 0-63 characters
• Allowed characters: alphanumeric , -, _, and .
• Must begin and end with an alphanumeric character
• Empty values are allowed

Selectors

Example label selector

cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list.

eg: env=dev,!chargeback-code,tier in (backend,worker)

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

A requirement consists of a key, an operator, and optional value(s).

Requirement	Format	Description
existence	key	Returns all resources that have been assigned a label with the given key (with any value)
non-existence	!key	Returns all resources that have not been assigned a label with the given key (with any value)
equality	key=value or key==value	Returns all resources that have been assigned a label with the given key and value
inequality	key!=value	Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion	key in (value1,value2…)	Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion	key notin (value1,value2…)	Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)

See the metadata documentation for more information.

Updating labels and annotations

Example Initial Metadata

{
  "metadata": {
    "labels": {
      "environment": "staging",
      "ready-to-deploy": "true"
    },
    "annotations": {
       "spring-version": "5.1",
       "app-version": "0.1-alpha"
     }
  }
}

Example Patch Request Body

{
  "metadata": {
    "labels": {
      "environment": "production",
      "ready-to-deploy": null
    },
    "annotations": {
       "app-version": "0.1",
       "deployed-month": "november"
     }
  }
}

Example Final Metadata

{
  "metadata": {
    "labels": {
      "environment": "production"
    },
    "annotations": {
       "spring-version": "5.1",
       "app-version": "0.1",
       "deployed-month": "november"
     }
  }
}

Labels and annotations can be updated by using the PATCH endpoint for their resource. For example, to update labels or annotations on an app, use the update an app endpoint. When patching metadata, CAPI endpoints do a deep merge, only updating labels or annotations that are specified in the request.

Labels and annotations follow the same rules for patching and must be wrapped in the metadata object inside the request body

• To create, include the new key with a value
• To change, include the existing key with a new value
• To delete, include the existing key with a null value
• To remain unchanged, do not include the existing key.

Pagination

Example Paginated Response

{
  "pagination": {
    "total_results": 3,
    "total_pages": 3,
    "first": {
      "href": "https://api.example.org/v3/people?page=1&per_page=1"
    },
    "last": {
      "href": "https://api.example.org/v3/people?page=3&per_page=1"
    },
    "next": {
      "href": "https://api.example.org/v3/people?page=2&per_page=1"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
      "created_at": "2016-03-18T23:26:46Z",
      "updated_at": "2016-10-17T20:00:42Z",

      "name": "Bob",

      "links": {
        "self": {
          "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
        }
      }
    }
  ]
}

Any request that can return multiple resources will be paginated and contain a pagination object and list of resources. Requests for multiple resources can use page, per_page, and order_by in addition to filters specific to the endpoint.

The pagination object

Name	Type	Description
total_results	integer	Total number of resources for all pages.
total_pages	integer	Total number of pages.
first	link object	Link to the first page.
last	link object	Link to the last page.
next	link object	Link to the next page.
previous	link object	Link to the previous page.

Procfiles

Example Ruby Procfile

web: bundle exec rackup config.ru -p $PORT
rake: bundle exec rake
worker: bundle exec rake workers:start

A Procfile enables you to declare required runtime processes, called process types, for your app. Procfiles must be named Procfile exactly, and placed in the root directory of your application.

In a Procfile, you declare one process type per line and use the syntax PROCESS_TYPE: COMMAND.

• PROCESS_TYPE defines the type of the process.
• COMMAND is the command line to launch the process.

Procfile use cases

Many buildpacks provide their own process types and commands by default; however, there are special cases where specifying a custom COMMAND is necessary. Commands can be overwritten by providing a Procfile with the same process type.

For example, a buildpack may provide a worker process type that runs the rake default:start command. If a Procfile is provided that also contains a worker process type, but a different command such as rake custom:start, the rake custom:start command will be used.

Some buildpacks, such as Python, that work on a variety of frameworks, do not attempt to provide a default start command. For these cases, a Procfile should be used to specify any necessary commands for the app.

Web process

web is a special process type that is required for all applications. The web PROCESS_TYPE must be specified by either the buildpack or the Procfile.

Relationships

Relationships represent associations between resources. They can be used to create, read, update, and delete these associations.

Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted.

Not all resources implement every relationship operation listed below. See the docs for each resource to see how it interacts with its relationships.

The relationship object

The relationship object is a key-value pair that uniquely identifies a resource. In practice this is almost always the guid of a resource.

Name	Type	Description
guid	string	The unique identifier for the related resource.

To-one relationships

Example to-one relationship

{
  "data": {
    "guid": "[related-resource-guid]"
  }
}

Some relationships relate a resource to exactly one other resource. For example an app can belong to only one space.

To-one relationship object

Name	Type	Description
data	relationship object	A single relationship

Setting the to-one relationship while creating an object

curl "https://api.example.org/v3/books" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "color": "yellow",
    "relationships": {
      "publisher": {
        "data": {
          "guid": "publisher-guid"
        }
      }
    }
  }'

Modifying the to-one relationship

curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": {
      "guid": "publisher-guid"
    }
  }'

Removing the to-one relationship

curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "data": null }'

Viewing the to-one relationship

curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X GET \
  -H "Authorization: bearer [token]"

To-many relationships

Example to-many relationship

{
  "data": [
    { "guid": "[related-resource-guid-1]" },
    { "guid": "[related-resource-guid-2]" }
  ]
}

Some relationships relate an resource to several other resources. For example an Isolation Segment can be entitled to multiple organizations.

To-many relationship object

Name	Type	Description
data	array of relationship objects	An array of multiple relationships.

Adding related to-many resources

curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"author-guid-1" },
      { "guid":"author-guid-2" }
    ]
  }'

Replacing all to-many relationships

curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"author-guid-3" },
      { "guid":"author-guid-4" }
    ]
  }'

Removing all to-many relationships

curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "data": [] }'

Removing specific to-many relationships

curl "https://api.example.org/v3/books/[guid]/relationships/authors/[author-guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Viewing the to-many relationships

curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X GET \
  -H "Authorization: bearer [token]"

Status Codes

Cloud Foundry V3 API uses a subset of HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that can potentially be fixed by correcting the request, and codes in the 5xx range indicate an error on the server side.

HTTP Status Code	Description
200 OK	The request completed successfully.
201 Created	The request completed successfully and created a new resource.
202 Accepted	The request will be completed asynchronously.
204 No Content	The request completed successfully and did not return a body.
400 Bad Request	The request has malformed or invalid data.
401 Unauthenticated	The request requires an authenticated user.
403 Forbidden	The request cannot be performed by the user.
404 Not Found	The requested resource does not exist.
422 Unprocessable Entity	The request cannot be performed.
500 Internal Server Error	An unexpected error occurred.
502 Bad Gateway	An upstream service caused the request to fail.

Workflows

Many users will think of interactions with Cloud Foundry in terms of a single operation like cf push in order to upload an application to the platform, have it compiled, and schedule it to be run. Performing a push operation actually requires a client to orchestrate several requests to the API to accomplish the entire operation. This section is meant to explain how clients can perform complex workflows using the API.

Push V2 app and run a V3 task

As of CF-245, a V2 application is also available as a V3 application, allowing a user to run a V3 task against it.

1. Push an application: cf push v3-tasks-sample
2. 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;"}'
3. Get logs from task: cf logs v3-tasks-sample --recent
4. Check task state: cf curl /v3/apps/$(cf app v3-tasks-sample --guid)/tasks

For more information, see Create a task.

Resources

Apps

Apps are top-level objects that link together and contain configuration information for your packages, droplets, processes, tasks, and more.

The app object

Example App object

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STOPPED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
    },
    "current_droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
      "method": "POST"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
      "method": "POST"
    },
    "revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
    },
    "deployed_revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name	Type	Description
name	string	Name of the app.
state	string	Current desired state of the app. Valid values are STOPPED or STARTED.
lifecycle	lifecycle object	Provides the lifecycle object for the application.
guid	uuid	Unique identifier for the app.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
relationships.space (experimental)	to-one relationship	The space the app is contained in.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the app.
metadata.annotations (experimental)	annotation object	Annotations added to the app.

Create an app

Example Request

curl "https://api.example.org/v3/apps" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_app",
    "relationships": {
      "space": {
        "data": {
          "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STOPPED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
    },
    "current_droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
      "method": "POST"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
      "method": "POST"
    },
    "revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
    },
    "deployed_revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/apps

Required parameters

Name	Type	Description
name	string	Name of the app.
relationships.space	to-one relationship	A relationship to a space.

Optional parameters

Name	Type	Description	Default
environment_variables	object	Environment variables to be used for the App when running.	{}
lifecycle	lifecycle object	Provides the lifecycle object for the application.	buildpack lifecycle
metadata.labels (experimental)	label object	Labels applied to the app.
metadata.annotations (experimental)	annotation object	Annotations applied to the app.

Permitted roles

Admin
Space Developer

Get an app

Example Request

curl "https://api.example.org/v3/apps/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STOPPED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
    },
    "current_droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
      "method": "POST"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
      "method": "POST"
    },
    "revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
    },
    "deployed_revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

GET /v3/apps/:guid

Query parameters

Name	Type	Description
include	string	Experimental - Optionally include additional related resources in the response. Valid values are space, org or space,org

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List apps

Example Request

curl "https://api.example.org/v3/apps" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/apps?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/apps?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/apps?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
        "name": "my_app",
        "state": "STARTED",
        "created_at": "2016-03-17T21:41:30Z",
        "updated_at": "2016-03-18T11:32:30Z",
        "lifecycle": {
          "type": "buildpack",
          "data": {
            "buildpacks": ["java_buildpack"],
            "stack": "cflinuxfs3"
          }
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
            }
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
          },
          "space": {
            "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
          },
          "processes": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
          },
          "packages": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
          },
          "environment_variables": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
          },
          "current_droplet": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
          },
          "droplets": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
          },
          "tasks": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
          },
          "start": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
            "method": "POST"
          },
          "stop": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
            "method": "POST"
          },
          "revisions": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
          },
          "deployed_revisions": {
            "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
          }
        },
        "metadata": {
          "labels": {},
          "annotations": {}
        }
      },
      {
        "guid": "02b4ec9b-94c7-4468-9c23-4e906191a0f8",
        "name": "my_app2",
        "state": "STOPPED",
        "created_at": "1970-01-01T00:00:02Z",
        "updated_at": "2016-06-08T16:41:26Z",
        "lifecycle": {
          "type": "buildpack",
          "data": {
            "buildpacks": ["ruby_buildpack"],
            "stack": "cflinuxfs3"
          }
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
            }
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
          },
          "space": {
            "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
          },
          "processes": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes"
          },
          "packages": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages"
          },
          "environment_variables": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables"
          },
          "current_droplet": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current"
          },
          "droplets": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets"
          },
          "tasks": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks"
          },
          "start": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start",
            "method": "POST"
          },
          "stop": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop",
            "method": "POST"
          },
          "revisions": {
            "href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions"
          },
          "deployed_revisions": {
            "href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed"
          }
        },
        "metadata": {
          "labels": {},
          "annotations": {}
        }
      }
    ]
  }

Retrieve all apps the user has access to.

Definition

GET /v3/apps

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of app guids to filter by.
names	list of strings	Comma-delimited list of app names to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
stacks	list of strings	Comma-delimited list of stack names to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, name.
label_selector	string	Experimental - A query string containing a list of label selector requirements.
include	string	Experimental - Optionally include a list of unique related resources in the response. Valid values are space and org, and are separated by a ,
lifecycle_type	string	Lifecycle type to filter by. Valid values are buildpack, docker.

Permitted roles

All Roles

Update an app

Example Request

curl "https://api.example.org/v3/apps/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_app",
    "lifecycle": {
      "type": "buildpack",
      "data": {
        "buildpacks": ["java_buildpack"]
      }
    }
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STARTED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-03-18T11:32:30Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
    },
    "current_droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
      "method": "POST"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
      "method": "POST"
    },
    "revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
    },
    "deployed_revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

PATCH /v3/apps/:guid

Optional parameters

Name	Type	Description
name	string	Name of the app.
lifecycle	lifecycle object	Lifecycle to be used when updating the app. Note: data is a required field in lifecycle if lifecycle is updated.
metadata.labels (experimental)	label object	Labels applied to the app.
metadata.annotations (experimental)	annotation object	Annotations applied to the app.

Permitted roles

Admin
Space Developer

Delete an app

Example Request

curl "https://api.example.org/v3/apps/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/apps/:guid

Permitted roles

Admin
Space Developer

Get current droplet

Example Request

curl "https://api.example.org/v3/apps/[guid]/droplets/current" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {}
  },
  "execution_metadata": "",
  "process_types": {
    "rake": "bundle exec rake",
    "web": "bundle exec rackup config.ru -p $PORT"
  },
  "checksum": {
    "type": "sha256",
    "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "buildpacks": [
    {
      "name": "ruby_buildpack",
      "detect_output": "ruby 1.6.14",
      "version": "1.1.1.",
      "buildpack_name": "ruby"
    }
  ],
  "stack": "cflinuxfs3",
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
      "method": "PATCH"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

GET /v3/apps/:guid/droplets/current

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Get current droplet association for an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/relationships/current_droplet" \
  -X GET \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet"
    },
    "related": {
      "href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/droplets/current"
    }
  }
}

This endpoint retrieves the current droplet relationship for an app.

Definition

GET /v3/apps/:guid/relationships/current_droplet

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Get environment for an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/env" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "staging_env_json": {
    "GEM_CACHE": "http://gem-cache.example.org"
  },
  "running_env_json": {
    "HTTP_PROXY": "http://proxy.example.org"
  },
  "environment_variables": {
    "RAILS_ENV": "production"
  },
  "system_env_json": {
    "VCAP_SERVICES": {
      "mysql": [
        {
          "name": "db-for-my-app",
          "label": "mysql",
          "tags": ["relational", "sql"],
          "plan": "xlarge",
          "credentials": {
            "username": "user",
            "password": "top-secret"
           },
          "syslog_drain_url": "https://syslog.example.org/drain",
          "provider": null
        }
      ]
    }
  },
  "application_env_json": {
    "VCAP_APPLICATION": {
      "limits": {
        "fds": 16384
      },
      "application_name": "my_app",
      "application_uris": [ "my_app.example.org" ],
      "name": "my_app",
      "space_name": "my_space",
      "space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
      "uris": [ "my_app.example.org" ],
      "users": null
    }
  }
}

Retrieve the environment variables that will be provided to an app at runtime. It will include environment variables for Environment Variable Groups and Service Bindings.

Definition

GET /v3/apps/:guid/env

Permitted roles

Admin
Admin Read-Only
Space Developer

Get environment variables for an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/environment_variables" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "var": {
    "RAILS_ENV": "production"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/[guid]/environment_variables"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/[guid]"
    }
  }
}

Retrieve the environment variables that are associated with the given app. For the entire list of environment variables that will be available to the app at runtime, see the env endpoint.

Definition

GET /v3/apps/:guid/environment_variables

Permitted roles

Admin
Admin Read-Only
Space Developer

Set current droplet

Example Request

curl "https://api.example.org/v3/apps/[guid]/relationships/current_droplet" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "data": { "guid": "[droplet_guid]" } }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet"
    },
    "related": {
      "href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/droplets/current"
    }
  }
}

Set the current droplet for an app. The current droplet is the droplet that the app will use when running.

Definition

PATCH /v3/apps/:guid/relationships/current_droplet

Permitted roles

Admin
Space Developer

Start an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/actions/start" \
  -X POST \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STARTED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-03-18T11:32:30Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
    },
    "current_droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
      "method": "POST"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
      "method": "POST"
    },
    "revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
    },
    "deployed_revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/apps/:guid/actions/start

Permitted roles

Admin
Space Developer

Stop an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/actions/stop" \
  -X POST \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STOPPED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-03-18T11:32:30Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
    },
    "current_droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
      "method": "POST"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
      "method": "POST"
    },
    "revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
    },
    "deployed_revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/apps/:guid/actions/stop

Permitted roles

Admin
Space Developer

Update environment variables for an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/environment_variables" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: bearer [token]" \
  -d '{
     "var": {
       "DEBUG": "false"
     }
   }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "var": {
    "RAILS_ENV": "production",
    "DEBUG": "false"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/[guid]/environment_variables"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/[guid]"
    }
  }
}

Update the environment variables associated with the given app. The variables given in the request will be merged with the existing app environment variables. Any requested variables with a value of null will be removed from the app. Environment variable names may not start with VCAP_. PORT is not a valid environment variable.

Definition

PATCH /v3/apps/:guid/environment_variables

Permitted roles

Admin
Space Developer

Builds

Builds represent the process of staging an application package. There are two types (lifecycles) of builds: buildpack and docker.

After an application is created and packages are uploaded, a build resource can be created to initiate the staging process. A successful build results in a droplet.

The build object

Example Build object

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs3"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": {
    "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
    "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    }
  }
}

Name	Type	Description
state	string	State of the build. Valid states are STAGING, STAGED, or FAILED.
error	string	A string describing errors during the build process.
lifecycle	lifecycle object	An object describing the lifecycle that was configured or discovered from the app.
package	object	The package that is the input to the staging process.
droplet	object	A resulting droplet from the staging process.
guid	uuid	Unique identifier for the build.
created_at	datetime	The time with zone when the build was created.
updated_at	datetime	The time with zone when the build was last updated.
created_by	object	The user that created the build.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the build.
metadata.annotations (experimental)	annotation object	Annotations applied to the build.

Create a build

Example Request

curl "https://api.example.org/v3/builds" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "package": {
       "guid": "[package-guid]"
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGING",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs3"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": null,
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    }
  }
}

Definition

POST /v3/builds

Required parameters

Name	Type	Description
package	object	App package to stage.

Optional parameters

Name	Type	Description	Default
lifecycle	lifecycle object	Lifecycle information for a build.	lifecycle on the app
metadata.labels (experimental)	label object	Labels applied to the build.
metadata.annotations (experimental)	annotation object	Annotations applied to the build.

Permitted roles

Admin
Space Developer

Get a build

Example Request

curl "https://api.example.org/v3/builds/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs3"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": {
    "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
    "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    }
  }
}

Definition

GET /v3/builds/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List builds

Example Request

curl "https://api.example.org/v3/builds" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "created_by": {
        "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
        "name": "bill",
        "email": "[email protected]"
      },
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": "cflinuxfs3"
        }
      },
      "package": {
        "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
      },
      "droplet": null,
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        }
      }
    }
  ]
}

Retrieve all builds the user has access to.

Definition

GET /v3/builds

Query parameters

Name	Type	Description
states	list of strings	Comma-delimited list of build states to filter by.
app_guids	list of strings	Comma-delimited list of app guids to filter by.
package_guids	list of strings	Comma-delimited list of package guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List builds for an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/builds" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/apps/[guid]/builds?states=STAGING&page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/[guid]/builds?states=STAGING&page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "created_by": {
        "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
        "name": "bill",
        "email": "[email protected]"
      },
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": "cflinuxfs3"
        }
      },
      "package": {
        "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
      },
      "droplet": null,
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        }
      }
    }
  ]
}

Retrieve all builds for the app.

Definition

GET /v3/apps/:guid/builds

Query parameters

Name	Type	Description
states	list of strings	Comma-delimited list of build states to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a build

Example Request

curl "https://api.example.org/v3/builds/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs3"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": {
    "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
    "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
  },
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    }
  }
}

Definition

PATCH /v3/builds/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the build.
metadata.annotations (experimental)	annotation object	Annotations applied to the build.

Permitted roles

Admin
Space Developer

Buildpacks

Buildpacks are used during a build to download external dependencies and transform a package into an executable droplet. In this way, buildpacks are a pluggable extension to Cloud Foundry that enable CF to run different languages and frameworks. Buildpacks will automatically detect if they support an application. Buildpacks can also be explicitly specified on apps and builds.

The buildpack object

Example Buildpack object

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "enabled": true,
    "locked": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
      },
      "upload": {
          "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
          "method": "POST"
      }
    }
  }

Name	Type	Description
guid	uuid	Unique identifier for the buildpack.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
name	string	The name of the buildpack. To be used by app buildpack field. (only alphanumeric characters)
state	string	The state of the buildpack. Valid value is: AWAITING_UPLOAD
filename	string	The filename of the buildpack.
stack	string	The name of the stack that the buildpack will use.
position	integer	The order in which the buildpacks are checked during buildpack auto-detection.
enabled	boolean	Whether or not the buildpack can be used for staging
locked	boolean	Whether or not the buildpack is locked to prevent updating the bits
links	links object	Links to related resources.

Create a buildpack

Example Request

curl "https://api.example.org/v3/buildpacks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "ruby_buildpack",
    "position": 42,
    "enabled": true,
    "locked": false,
    "stack": "windows64"
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "enabled": true,
    "locked": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
      },
      "upload": {
          "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
          "method": "POST"
      }
    }
  }

Definition

POST /v3/buildpacks

Required parameters

Name	Type	Description
name	string	Name of the buildpack.

Optional parameters

Name	Type	Description	Default
stack	string	The name of the stack that the buildpack will use.	null
position	integer	The order in which the buildpacks are checked during buildpack auto-detection.	1
enabled	boolean	Whether or not the buildpack will be used for staging	true
locked	boolean	Whether or not the buildpack is locked to prevent updating the bits	false
metadata.labels (experimental)	label object	Labels applied to the buildpack.
metadata.annotations (experimental)	annotation object	Annotations applied to the buildpack.

Permitted roles

Admin

Get a buildpack

Example Request

curl "https://api.example.org/v3/buildpacks/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "enabled": true,
    "locked": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
      },
      "upload": {
          "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
          "method": "POST"
      }
    }
  }

Definition

GET /v3/buildpacks/:guid

Permitted roles

All Roles

List buildpacks

Example Request

curl "https://api.example.org/v3/buildpacks" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/buildpacks?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/buildpacks?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/buildpacks?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
        "created_at": "2016-03-18T23:26:46Z",
        "updated_at": "2016-10-17T20:00:42Z",
        "name": "my-buildpack",
        "state": "AWAITING_UPLOAD",
        "filename": null,
        "stack": "my-stack",
        "position": 1,
        "enabled": true,
        "locked": false,
        "metadata": {
          "labels": {},
          "annotations": {}
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
          },
          "upload": {
            "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
            "method": "POST"
          }
        }
      }
    ]
  }

Retrieve all buildpacks the user has access to.

Definition

GET /v3/buildpacks

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
names	list of strings	Comma-delimited list of buildpack names to filter by.
stacks	list of strings	Comma-delimited list of stack names to filter by.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and position.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

Update a buildpack

Example Request

curl "https://api.example.org/v3/buildpacks/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "ruby_buildpack",
    "position": 42,
    "enabled": true,
    "locked": false,
    "stack": "windows64"
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "enabled": true,
    "locked": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
      },
      "upload": {
          "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
          "method": "POST"
      }
    }
  }

Definition

PATCH /v3/buildpacks/:guid

Optional parameters

Name	Type	Description
name	string	Name of the buildpack.
stack	string	The name of the stack that the buildpack will use.
position	integer	The order in which the buildpacks are checked during buildpack auto-detection.
enabled	boolean	Whether or not the buildpack will be used for staging
locked	boolean	Whether or not the buildpack is locked to prevent updating the bits
metadata.labels (experimental)	label object	Labels applied to the buildpack.
metadata.annotations (experimental)	annotation object	Annotations applied to the buildpack.

Permitted roles

Admin

Delete a buildpack

Example Request

curl "https://api.example.org/v3/buildpacks/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/buildpacks/:guid

Permitted Roles

Admin

Upload buildpack bits

Example Request

curl "https://api.example.org/v3/buildpacks/[guid]/upload" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -F bits=@"buildpack.zip"

Example Response

HTTP/1.1 202 OK
Content-Type: application/json
Location: https://api.example.org/v3/jobs/[guid]

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "enabled": true,
    "locked": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
      },
      "upload": {
          "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
          "method": "POST"
      }
    }
  }

Upload a zip file containing a Cloud Foundry compatible buildpack. The file must be sent as part of a multi-part form.

Definition

POST /v3/buildpacks/:guid/upload

Required parameters

Name	Type	Description
bits	form field	A binary zip file containing the buildpack bits.

Permitted roles

Admin

Domains

Domains represent a fully qualified domain name that is used for application routes.

A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.

The domain object

Example Domain object

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Name	Type	Description
guid	uuid	Unique identifier for the domain.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
name	string	The name of the domain. Must be between 3 ~ 253 characters and follow RFC 1035.
internal	boolean	Whether the domain is used for internal (container-to-container) traffic.
organization	to-one relationship	The organization the domain is scoped to. If set, the domain will only be available in that organization. Otherwise, the domain will be globally available.
shared_organizations	to-many relationship	Organizations the domain is shared with. If set, the domain will be available in these organizations in addition to the organization the domain is scoped to.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the domain.
metadata.annotations (experimental)	annotation object	Annotations applied to the domain.

Create a domain

Example Request

curl "https://api.example.org/v3/domains" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "example.com",
    "internal": false
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Definition

POST /v3/domains

Required parameters

Name	Type	Description
name	string	Name of the domain.

Optional parameters

Name	Type	Description	Default
internal	boolean	Whether the domain is used for internal (container-to-container) traffic.	false
organization	to-one relationship	A relationship to the organization the domain will be scoped to. Note: can not be used with the internal param
shared_organizations	to-many relationship	A relationship to organizations the domain will be shared with. Note: can not be used without an organization relationship
metadata.labels (experimental)	label object	Labels applied to the domain.
metadata.annotations (experimental)	annotation object	Annotations applied to the domain.

Permitted roles

Role	Notes
Admin
Org Manager	When an organization relationship is provided.

Get a domain

Example Request

curl "https://api.example.org/v3/domains/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Definition

GET /v3/domains/:guid

Permitted roles

Roles	Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor
Org Billing Manager	Can only view domains without an organization relationship.
Org Manager
Space Auditor
Space Developer
Space Manager

List domains

Example Request

curl "https://api.example.org/v3/domains" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/domains?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/domains?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/domains?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
        "created_at": "2019-03-08T01:06:19Z",
        "updated_at": "2019-03-08T01:06:19Z",
        "name": "test-domain.com",
        "internal": false,
        "metadata": {
          "labels": {},
          "annotations": {}
        },
        "relationships": {
          "organization": {
            "data": null
          },
          "shared_organizations": {
            "data": []
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
          },
          "route_reservations": {
            "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
          },
        }
      }
    ]
  }

Retrieve all domains the user has access to.

Definition

GET /v3/domains

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of guids to filter by.
names	list of strings	Comma-delimited list of domain names to filter by.
organization_guids	list of strings	Comma-delimited list of owning organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List domains for an organization

Example Request

curl "https://api.example.org/v3/organizations/[guid]/domains" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/domains?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/domains?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/domains?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
        "created_at": "2019-03-08T01:06:19Z",
        "updated_at": "2019-03-08T01:06:19Z",
        "name": "test-domain.com",
        "internal": false,
        "metadata": {
          "labels": {},
          "annotations": {}
        },
        "relationships": {
          "organization": {
            "data": null
          },
          "shared_organizations": {
            "data": []
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
          },
          "route_reservations": {
            "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
          },
        }
      }
    ]
  }

Retrieve all domains available in an organization for the current user. This will return user-visible domains without an organization relationship AND domains scoped or shared with the organization.

Definition

GET /v3/organizations/:guid/domains

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of guids to filter by.
names	list of strings	Comma-delimited list of domain names to filter by.
organization_guids	list of strings	Comma-delimited list of owning organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

Update a domain

Example Request

curl "https://api.example.org/v3/domains/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "metadata": {
      "labels": {"key": "value"},
      "annotations": {"note": "detailed information"}
    }
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { "key": "value" },
      "annotations": { "note": "detailed information" }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Definition

PATCH /v3/domains/:guid

Optional parameters

Name	Type	Description	Default
metadata.labels (experimental)	label object	Labels applied to the domain.
metadata.annotations (experimental)	annotation object	Annotations applied to the domain.

Permitted roles

Role	Notes
Admin
Org Manager	If domain is scoped to organization managed by the org manager.

Delete a domain

Example Request

curl "https://api.example.org/v3/domains/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/domains/:guid

Permitted roles

Role	Notes
Admin
Org Manager	If domain is scoped to organization managed by the org manager.

Share a domain

Example Request

curl "https://api.example.org/v3/domains/[guid]/relationships/shared_organizations" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
      {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
    ]
  }'

Example Response

HTTP/1.1 200 Created
Content-Type: application/json

  {
    "data": [
      {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"}
      {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
    ]
  }

This endpoint shares an organization-scoped domain to other organizations specified by a list of organization guids. This will allow any of the other organizations to use the organization-scoped domain.

Definition

POST /v3/domains/:guid/relationships/shared_organizations

Required parameters

Name	Type	Description
data	to-many relationship	The organization guids with which to share the domain.

Permitted roles

Role	Notes
Admin
Org Manager

Unshare a domain

Example Request

curl "https://api.example.org/v3/domains/[guid]/relationships/shared_organizations/[org_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json"

Example Response

HTTP/1.1 204 No Content

This endpoint removes an organization from the list of organizations an organization-scoped domain is shared with. This prevents the organization from using the organization-scoped domain.

Definition

DELETE /v3/domains/:guid/relationships/shared_organizations/:org_guid

Permitted roles

Role	Notes
Admin
Org Manager	Can be in either the domain’s owning organization or the organization it has been shared to

Droplets

Droplets are the result of staging an application package. There are two types (lifecycles) of droplets: buildpack and docker. In the case of the buildpacks, the droplet contains the bits produced by the buildpack, typically application code and dependencies.

After an application is created and packages are uploaded, a droplet must be created via a build in order for an application to be deployed or tasks to be run. The current droplet must be assigned to an application before it may be started. When tasks are created, they either use a specific droplet guid, or use the current droplet assigned to an application.

The droplet object

Example Droplet object

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {}
  },
  "execution_metadata": "",
  "process_types": {
    "rake": "bundle exec rake",
    "web": "bundle exec rackup config.ru -p $PORT"
  },
  "checksum": {
    "type": "sha256",
    "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "buildpacks": [
    {
      "name": "ruby_buildpack",
      "detect_output": "ruby 1.6.14",
      "version": "1.1.1.",
      "buildpack_name": "ruby"
    }
  ],
  "stack": "cflinuxfs3",
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
      "method": "PATCH"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name	Type	Description
state	string	State of the droplet. Valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, STAGED, COPYING, FAILED, or EXPIRED.
error	string	A string describing the last error during the droplet lifecycle.
lifecycle	lifecycle object	An object describing the lifecycle that was configured or discovered from the app. lifecycle.data will always be an empty hash for a droplet object.
guid	uuid	Unique identifier for the droplet.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.
execution_metadata	string	Serialized JSON data resulting from staging for use when executing a droplet.
process_types	object	The process types (keys) and associated start commands (values) that will be created when the droplet is executed.
metadata.labels (experimental)	labels object	Labels on the droplet
metadata.annotations (experimental)	annotations object	Annotations on the droplet

In addition to these fields, a droplet object will contain the following fields from both lifecycles. Their values will be null by default and will contain values when the droplet is of a specific lifecycle.type.

Buildpack droplet

Name	Type	Description
checksum.type	string	Hashing algorithm for checksum. Supported algorithms are sha256 and sha1.
checksum.value	string	Checksum of droplet.
buildpacks	array of detected buildpack objects	Detected buildpacks from the staging process.
stack	string	The root filesystem to use with the buildpack, for example cflinuxfs3

Detected buildpack object

Name	Type	Description
name	string	System buildpack name
detect_output	string	Output during buildpack detect process
buildpack_name	string	Name reported by the buildpack
version	string	Version reported by the buildpack

Docker droplet

Name	Type	Description
image	string	Docker image name.

Create a droplet

Example Request

curl "https://api.example.org/v3/droplets" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "relationships": {
      "app": {
        "data": {
          "guid": "[app-guid]"
        }
      }
    },
    "process_types": {
      "rake": "bundle exec rake",
      "web": "bundle exec rackup config.ru -p $PORT"
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "AWAITING_UPLOAD",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {}
  },
  "execution_metadata": "",
  "process_types": {
    "rake": "bundle exec rake",
    "web": "bundle exec rackup config.ru -p $PORT"
  },
  "checksum": {
    "type": "sha256",
    "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "buildpacks": [
    {
      "name": "ruby_buildpack",
      "detect_output": "ruby 1.6.14",
      "version": "1.1.1.",
      "buildpack_name": "ruby"
    }
  ],
  "stack": "cflinuxfs3",
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
      "method": "PATCH"
    },
    "upload": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/upload",
      "method": "POST"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

This endpoint is only for creating a droplet without a package. To create a droplet based on a package, see Create a build.

Definition

POST /v3/droplets

Required parameters

Name	Type	Description
app	to-one relationship	App to create droplet for.

Optional parameters

Name	Type	Description	Default
process_types	hash	Process names and start commands for the droplet.	{"web": ""}

Permitted roles

Admin
Space Developer

Get a droplet

Example Request

curl "https://api.example.org/v3/droplets/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {}
  },
  "execution_metadata": "",
  "process_types": {
    "rake": "bundle exec rake",
    "web": "bundle exec rackup config.ru -p $PORT"
  },
  "checksum": {
    "type": "sha256",
    "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "buildpacks": [
    {
      "name": "ruby_buildpack",
      "detect_output": "ruby 1.6.14",
      "version": "1.1.1.",
      "buildpack_name": "ruby"
    }
  ],
  "stack": "cflinuxfs3",
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
      "method": "PATCH"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

GET /v3/droplets/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List droplets

Example Request

curl "https://api.example.org/v3/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {}
      },
      "image": null,
      "execution_metadata": "PRIVATE DATA HIDDEN",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "checksum": {
        "type": "sha256",
        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "buildpacks": [
        {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14",
          "version": "1.1.1.",
          "buildpack_name": "ruby"
        }
      ],
      "stack": "cflinuxfs3",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
          "method": "PATCH"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "image": "cloudfoundry/diego-docker-app-custom:latest",
      "checksum": null,
      "buildpacks": null,
      "stack": null,
      "created_at": "2016-03-17T00:00:01Z",
      "updated_at": "2016-03-17T21:41:32Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
          "method": "PATCH"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve all droplets the user has access to.

Definition

GET /v3/droplets

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of droplet guids to filter by.
states	list of strings	Comma-delimited list of droplet states to filter by.
app_guids	list of strings	Comma-delimited list of app guids to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at and updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List droplets for a package

Example Request

curl "https://api.example.org/v3/packages/[guid]/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {}
      },
      "image": null,
      "execution_metadata": "PRIVATE DATA HIDDEN",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "checksum": {
        "type": "sha256",
        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "buildpacks": [
        {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14",
          "version": "1.1.1.",
          "buildpack_name": "ruby"
        }
      ],
      "stack": "cflinuxfs3",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
          "method": "PATCH"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "image": "cloudfoundry/diego-docker-app-custom:latest",
      "checksum": null,
      "buildpacks": null,
      "stack": null,
      "created_at": "2016-03-17T00:00:01Z",
      "updated_at": "2016-03-17T21:41:32Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
          "method": "PATCH"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve a list of droplets belonging to a package.

Definition

GET /v3/packages/:guid/droplets

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of droplet guids to filter by.
states	list of strings	Comma-delimited list of droplet states to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at and updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List droplets for an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {}
      },
      "image": null,
      "execution_metadata": "PRIVATE DATA HIDDEN",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "checksum": {
        "type": "sha256",
        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "buildpacks": [
        {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14",
          "version": "1.1.1.",
          "buildpack_name": "ruby"
        }
      ],
      "stack": "cflinuxfs3",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
          "method": "PATCH"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "image": "cloudfoundry/diego-docker-app-custom:latest",
      "checksum": null,
      "buildpacks": null,
      "stack": null,
      "created_at": "2016-03-17T00:00:01Z",
      "updated_at": "2016-03-17T21:41:32Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
          "method": "PATCH"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve a list of droplets belonging to an app.

Definition

GET /v3/apps/:guid/droplets

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of droplet guids to filter by.
states	list of strings	Comma-delimited list of droplet states to filter by.
current	boolean	If true, only include the droplet currently assigned to the app.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at and updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a droplet

Example Request

curl "https://api.example.space/v3/droplets/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
    "state": "STAGED",
    "error": null,
    "lifecycle": {
      "type": "buildpack",
      "data": {}
    },
    "execution_metadata": "",
    "process_types": {
      "rake": "bundle exec rake",
      "web": "bundle exec rackup config.ru -p $PORT"
    },
    "checksum": {
      "type": "sha256",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    },
    "buildpacks": [
      {
        "name": "ruby_buildpack",
        "detect_output": "ruby 1.6.14",
        "version": "1.1.1.",
        "buildpack_name": "ruby"
      }
    ],
    "stack": "cflinuxfs3",
    "image": null,
    "created_at": "2016-03-28T23:39:34Z",
    "updated_at": "2016-03-28T23:39:47Z",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
      },
      "package": {
        "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
      },
      "app": {
        "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
      },
      "assign_current_droplet": {
        "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
        "method": "PATCH"
      }
    },
    "metadata": {
      "labels": {
        "release": "stable"
      },
      "annotations": {
        "note": "detailed information"
      }
    }
  }

Definition

PATCH /v3/droplets/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the droplet.
metadata.annotations (experimental)	annotation object	Annotations applied to the droplet.

Permitted roles

Admin
Org Manager
Space Developer
Space Manager

Delete a droplet

Example Request

curl "https://api.example.org/v3/droplets/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/droplets/:guid

Permitted Roles

Admin
Space Developer

Copy a droplet

Example Request

curl "https://api.example.org/v3/droplets?source_guid=[guid]" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "relationships": {
      "app": {
        "data": {
          "guid": "[app-guid]"
        }
      }
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "COPYING",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {}
  },
  "execution_metadata": "",
  "process_types": null,
  "checksum": null,
  "buildpacks": null,
  "stack": null,
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
      "method": "PATCH"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Copy a droplet to a different app. The copied droplet excludes the environment variables listed on the source droplet.

Definition

POST /v3/droplets?source_guid=:guid

Required query parameters

Name	Type	Description
source_guid	uuid	Source guid of the droplet to be copied.

Required parameters

Name	Type	Description
relationships.app	to-one relationship	A relationship to the destination app.

Permitted roles

Admin
Space Developer

Upload droplet bits

Example Request

curl "https://api.example.org/v3/droplets/[guid]/upload" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -F bits=@"droplet.tgz"

Example Response

HTTP/1.1 202 OK
Content-Type: application/json
Location: https://api.example.org/v3/jobs/[guid]

{
  "guid": "3c64aba2-2d9e-4eea-9e07-6fec1636315e",
  "state": "PROCESSING_UPLOAD",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {}
  },
  "checksum": null,
  "buildpacks": [],
  "stack": null,
  "image": null,
  "execution_metadata": "",
  "process_types": {
    "rake": "bundle exec rake",
    "web": "bundle exec rackup config.ru -p $PORT"
  },
  "created_at": "2019-05-15T22:43:54Z",
  "updated_at": "2019-05-15T22:53:02Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/3c64aba2-2d9e-4eea-9e07-6fec1636315e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4/relationships/current_droplet",
      "method": "PATCH"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Upload a gzip compressed tarball file containing a Cloud Foundry compatible droplet. The file must be sent as part of a multi-part form.

Definition

POST /v3/droplets/:guid/upload

Required parameters

Name	Type	Description
bits	form field	A gzip compressed tarball file with .tgz extension containing the droplet bits.

Permitted roles

Admin
Space Developer

Feature Flags

Feature flags are runtime flags that enable or disable functionality on the API.

The feature flag object

Example Feature Flag object

  {
    "name": "my_feature_flag",
    "enabled": true,
    "updated_at": "2016-10-17T20:00:42Z",
    "custom_error_message": "error message the user sees",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/feature_flags/my_feature_flag"
      }
    }
  }

Name	Type	Description
name	string	The name of the feature flag.
enabled	boolean	Whether the feature flag is enabled.
updated_at	datetime	The time with zone when the object was last updated. This will be blank for feature flags that have not been configured.
custom_error_message	string	The error string returned by the API when a client performs an action disabled by the feature flag.
links	links object	Links to related resources.

List of feature flags

Name: app_bits_upload Default: true Description: When enabled, space developers can upload app bits. When disabled, only admin users can upload app bits.
Name: app_scaling Default: true Description: When enabled, space developers can perform scaling operations (i.e. change memory, disk or instances). When disabled, only admins can perform scaling operations.
Name: diego_docker Default: false Description: When enabled, Docker applications are supported by Diego. When disabled, Docker applications will stop running. It will still be possible to stop and delete them and update their configurations.
Name: env_var_visibility Default: true Description: When enabled, all users can see their environment variables. When disabled, no users can see environment variables.
Name: hide_marketplace_from_unauthenticated_users Default: false Description: When enabled, service offerings available in the marketplace will be hidden from unauthenticated users. When disabled, unauthenticated users will be able to see the service offerings available in the marketplace.
Name: private_domain_creation Default: true Description: When enabled, an organization manager can create private domains for that organization. When disabled, only admin users can create private domains.
Name: route_creation Default: true Description: When enabled, a space developer can create routes in a space. When disabled, only admin users can create routes.
Name: service_instance_creation Default: true Description: When enabled, a space developer can create service instances in a space. When disabled, only admin users can create service instances.
Name: service_instance_sharing Default: false Description: When enabled, Space Developers can share service instances between two spaces (even across orgs!) in which they have the Space Developer role. When disabled, Space Developers cannot share service instances between two spaces.
Name: set_roles_by_username Default: true Description: When enabled, Org Managers or Space Managers can add access roles by username. In order for this feature to be enabled the CF operator must: 1) Enable the /ids/users/ endpoint for UAA 2) Create a UAA cloud_controller_username_lookup client with the scim.userids authority
Name: space_developer_env_var_visibility Default: true Description: When enabled, space developers can do a get on the /v2/apps/:guid/env and /v3/apps/:guid/env end points. When disabled, space developers can no longer do a get against these end points.
Name: space_scoped_private_broker_creation Default: true Description: When enabled, space developers can create space scoped private brokers. When disabled, only admin users can create create space scoped private brokers.
Name: task_creation Default: true Description: When enabled, space developers can create tasks. When disabled, only admin users can create tasks.
Name: unset_roles_by_username Default: true Description: When enabled, Org Managers or Space Managers can remove access roles by username. In order for this feature to be enabled the CF operator must: 1) Enable the /ids/users/ endpoint for UAA 2) Create a UAA cloud_controller_username_lookup client with the scim.userids authority
Name: user_org_creation Default: false Description: When enabled, any user can create an organization via the API. When disabled, only admin users can create organizations via the API.

Get a feature flag

Example Request

curl "https://api.example.org/v3/feature_flags/[name]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "name": "my_feature_flag",
    "enabled": true,
    "updated_at": "2016-10-17T20:00:42Z",
    "custom_error_message": "error message the user sees",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/feature_flags/my_feature_flag"
      }
    }
  }

Definition

GET /v3/feature_flags/:name

Permitted roles

All Roles

List feature flags

Example Request

curl "https://api.example.org/v3/feature_flags" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/feature_flags?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/feature_flags?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/feature_flags?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "name": "my_feature_flag",
        "enabled": true,
        "updated_at": "2016-10-17T20:00:42Z",
        "custom_error_message": "error message the user sees",
        "links": {
          "self": {
            "href": "https://api.example.org/v3/feature_flags/my_feature_flag"
          }
        }
      },
      {
        "name": "my_second_feature_flag",
        "enabled": false,
        "updated_at": null,
        "custom_error_message": null,
        "links": {
          "self": {
            "href": "https://api.example.org/v3/feature_flags/my_second_feature_flag"
          }
        }
      }
    ]
  }

Retrieve all feature_flags.

Definition

GET /v3/feature_flags

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to name ascending. Prepend with - to sort descending. Valid value is name.

Permitted roles

All Roles

Update a feature flag

Example Request

curl "https://api.example.org/v3/feature_flags/[name]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "enabled": true,
    "custom_error_message": "error message the user sees"
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "name": "my_feature_flag",
    "enabled": true,
    "updated_at": "2016-10-17T20:00:42Z",
    "custom_error_message": "error message the user sees",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/feature_flags/my_feature_flag"
      }
    }
  }

Definition

PATCH /v3/feature_flags/:name

Optional parameters

Name	Type	Description
enabled	boolean	Whether the feature flag is enabled.
custom_error_message	string	The error string returned by the API when a client performs an action disabled by the feature flag.

Permitted roles

Admin

Isolation Segments

Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.

The isolation segment object

Example Isolation Segment object

{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "name": "an_isolation_segment",
   "created_at": "2016-10-19T20:25:04Z",
   "updated_at": "2016-11-08T16:41:26Z",
   "links": {
      "self": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
      }
   },
   "metadata": {
      "annotations": {},
      "labels": {}
   }
}

Name	Type	Description
name	string	Name of the isolation segment.
guid	uuid	Unique identifier for the isolation segment.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.
metadata.labels (experimental)	labels object	Labels on the isolation segment
metadata.annotations (experimental)	annotations object	Annotations on the isolation segment

Create an isolation segment

Example Request

curl "https://api.example.org/v3/isolation_segments" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_segment"
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "name": "an_isolation_segment",
   "created_at": "2016-10-19T20:25:04Z",
   "updated_at": "2016-11-08T16:41:26Z",
   "links": {
      "self": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
      }
   },
   "metadata": {
      "annotations": {},
      "labels": {}
   }
}

Definition

POST /v3/isolation_segments

Required parameters

Name	Type	Description
name	string	Name of the Isolation Segment. Isolation Segment names must be unique across the entire system, and case is ignored when checking for uniqueness.
metadata.labels (experimental)	label object	Labels applied to the isolation segment.
metadata.annotations (experimental)	annotation object	Annotations applied to the isolation segment.

Permitted roles

Admin

Get an isolation segment

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "name": "an_isolation_segment",
   "created_at": "2016-10-19T20:25:04Z",
   "updated_at": "2016-11-08T16:41:26Z",
   "links": {
      "self": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
      }
   },
   "metadata": {
      "annotations": {},
      "labels": {}
   }
}

Definition

GET /v3/isolation_segments/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List isolation segments

Example Request

curl "https://api.example.org/v3/isolation_segments" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "pagination": {
      "total_results": 11,
      "total_pages": 3,
      "first": {
         "href": "https://api.example.org/v3/isolation_segments?page=1&per_page=5"
      },
      "last": {
         "href": "https://api.example.org/v3/isolation_segments?page=3&per_page=5"
      },
      "next": {
         "href": "https://api.example.org/v3/isolation_segments?page=2&per_page=5"
      },
      "previous": null
   },
   "resources": [
      {
         "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
         "name": "an_isolation_segment",
         "created_at": "2016-10-19T20:25:04Z",
         "updated_at": "2016-11-08T16:41:26Z",
         "links": {
            "self": {
               "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
            }
         },
         "metadata": {
            "annotations": {},
            "labels": {}
         }
      },
      {
         "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac",
         "name": "an_isolation_segment1",
         "created_at": "2016-10-19T20:29:19Z",
         "updated_at": "2016-11-08T16:41:26Z",
         "links": {
            "self": {
               "href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac/organizations"
            }
         },
         "metadata": {
            "annotations": {},
            "labels": {}
         }
      },
      {
         "guid": "ecdc67c3-a71e-43ff-bddf-048930b8cd03",
         "name": "an_isolation_segment2",
         "created_at": "2016-10-19T20:29:22Z",
         "updated_at": "2016-11-08T16:41:26Z",
         "links": {
            "self": {
               "href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03/organizations"
            }
         },
         "metadata": {
            "annotations": {},
            "labels": {}
         }
      },
      {
         "guid": "424c89e4-4353-46b7-9bf4-f90bd9bacac0",
         "name": "an_isolation_segment3",
         "created_at": "2016-10-19T20:29:27Z",
         "updated_at": "2016-11-08T16:41:26Z",
         "links": {
            "self": {
               "href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0/organizations"
            }
         },
         "metadata": {
            "annotations": {},
            "labels": {}
         }
      },
      {
         "guid": "0a79fcec-a648-4eb8-a6c3-2b5be39047c7",
         "name": "an_isolation_segment4",
         "created_at": "2016-10-19T20:29:33Z",
         "updated_at": "2016-11-08T16:41:26Z",
         "links": {
            "self": {
              "href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7/organizations"
            }
         },
         "metadata": {
            "annotations": {},
            "labels": {}
         }
      }
   ]
}

Retrieves all isolation segments to which the user has access. For admin, this is all the isolation segments in the system. For an org manager, this is the isolation segments in the allowed list for any organization to which the user belongs. For any other user, this is the isolation segments assigned to any spaces to which the user has access.

Definition

GET /v3/isolation_segments

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of isolation segment guids to filter by.
names	list of strings	Comma-delimited list of isolation segment names to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and name.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List organizations relationship

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
    },
    "related": {
      "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/organizations"
    }
  }
}

This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs.

Definition

GET /v3/isolation_segments/:guid/relationships/organizations

Permitted roles

All Roles

List spaces relationship

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/spaces" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
    }
  }
}

This endpoint lists the spaces to which the isolation segment is assigned. For an Admin, this will list all associated spaces in the system. For an org manager, this will list only those associated spaces belonging to orgs for which the user is a manager. For any other user, this will list only those associated spaces to which the user has access.

Definition

GET /v3/isolation_segments/:guid/relationships/spaces

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update an isolation segment

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "name": "my_isolation_segment" }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "name": "my_isolation_segment",
   "created_at": "2016-10-19T20:25:04Z",
   "updated_at": "2016-11-08T16:41:26Z",
   "links": {
      "self": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
      }
   },
   "metadata": {
      "annotations": {},
      "labels": {}
   }
}

Definition

PATCH /v3/isolation_segments/:guid

Optional parameters

Name	Type	Description
name	string	Name of the Isolation Segment. Isolation Segment names must be unique across the entire system, and case is ignored when checking for uniqueness.
metadata.labels (experimental)	label object	Labels applied to the isolation segment.
metadata.annotations (experimental)	annotation object	Annotations applied to the isolation segment.

Permitted roles

Admin

Delete an isolation segment

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

An isolation segment cannot be deleted if it is entitled to any organization.

Definition

DELETE /v3/isolation_segments/:guid

Permitted roles

Admin

Entitle organizations for an isolation segment

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"org-guid-1" },
      { "guid":"org-guid-2" }
    ]
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
    },
    "related": {
      "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/organizations"
    }
  }
}

This endpoint entitles the specified organizations for the isolation segment. In the case where the specified isolation segment is the system-wide shared segment, and if an organization is not already entitled for any other isolation segment, then the shared isolation segment automatically gets assigned as the default for that organization.

Definition

POST /v3/isolation_segments/:guid/relationships/organizations

Required parameters

Name	Type	Description
data	to-many relationship	Organization relationships. Each organization will be entitled to manage this isolation segment.

Permitted roles

Admin

Revoke entitlement to isolation segment for an organization

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations/[org_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

This endpoint revokes the entitlement for the specified organization to the isolation segment. If the isolation segment is assigned to a space within an organization, the entitlement cannot be revoked. If the isolation segment is the organization’s default, the entitlement cannot be revoked.

Definition

DELETE /v3/isolation_segments/:guid/relationships/organizations/:org_guid

Permitted roles

Admin

Jobs

Jobs are created by the platform when performing certain asynchronous actions.

The job object

Example Job object

{
  "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
  "created_at": "2016-10-19T20:25:04Z",
  "updated_at": "2016-11-08T16:41:26Z",
  "operation": "app.delete",
  "state": "COMPLETE",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
    }
  },
  "errors": []
}

Name	Type	Description
guid	uuid	Unique identifier for the job.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
operation	string	Current desired operation of the job on a model.
state	string	State of the job. Valid values are PROCESSING, COMPLETE, orFAILED.
links	links object	Links to related resources.
errors	errors list	Array of errors that occurred while processing the job.

Get a job

Example Request

curl "https://api.example.org/v3/jobs/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Completed Job Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
  "created_at": "2016-10-19T20:25:04Z",
  "updated_at": "2016-11-08T16:41:26Z",
  "operation": "app.delete",
  "state": "COMPLETE",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
    }
  },
  "errors": []
}

Failed Job Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
  "created_at": "2016-10-19T20:25:04Z",
  "updated_at": "2016-11-08T16:41:26Z",
  "operation": "app.delete",
  "state": "FAILED",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    }
  },
  "errors": [
    {
      "code": 10008,
      "title": "CF-UnprocessableEntity",
      "detail": "something went wrong"
    }
  ]
}

Definition

GET /v3/jobs/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Organizations

An org is a development account that an individual or multiple collaborators can own and use. All collaborators access an org with user accounts. Collaborators in an org share a resource quota plan, applications, services availability, and custom domains.

The organization object

Example Organization object

{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "suspended": false,
  "relationships": {
    "quota": {
      "data": {
        "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
    },
    "domains": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
    },
    "default_domain": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the organization.
name	string	Name of the organization.
suspended	boolean	Whether an organization is suspended or not. Non-admins will be blocked from creating, updating, or deleting resources in a suspended organization.
relationships.quota (experimental)	to-one relationship	The quota applied to the organization.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the organization.
metadata.annotations (experimental)	annotation object	Annotations added to the organization.

Create an organization

Example Request

curl "https://api.example.org/v3/organizations" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-organization" }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "suspended": false,
  "relationships": {
    "quota": {
      "data": {
        "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
    },
    "domains": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
    },
    "default_domain": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/organizations

Required parameters

Name	Type	Description
name	string	Organization name

Optional parameters

Name	Type	Description
suspended (experimental)	boolean	Whether an organization is suspended or not.
metadata.labels (experimental)	label object	Labels applied to the organization.
metadata.annotations (experimental)	annotation object	Annotations applied to the organization.

Permitted roles

Admin

If the user_org_creation feature flag is enabled, any user with the cloud_controller.write scope will be able to create organizations.

Get an organization

Example Request

curl "https://api.example.org/v3/organizations/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "suspended": false,
  "relationships": {
    "quota": {
      "data": {
        "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
    },
    "domains": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
    },
    "default_domain": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

This endpoint retrieves the specified organization object.

Definition

GET /v3/organizations/:guid

Permitted roles

All Roles

List organizations

Example Request

curl "https://api.example.org/v3/organizations" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/organizations?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/organizations?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "name": "org1",
      "suspended": false,
      "relationships": {
        "quota": {
          "data": {
            "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920"
        },
        "domains": {
          "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains"
        },
        "default_domain": {
          "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains/default"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
      "created_at": "2017-02-02T00:14:30Z",
      "updated_at": "2017-02-02T00:14:30Z",
      "name": "org2",
      "suspended": false,
      "relationships": {
        "quota": {
          "data": {
            "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
        },
        "domains": {
          "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains"
        },
        "default_domain": {
          "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains/default"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve all organizations the user has access to.

Definition

GET /v3/organizations

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of organization names to filter by.
guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and name.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List organizations for isolation segment

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]/organizations" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/isolation_segments/933b4c58-120b-499a-b85d-4b6fc9e2903b/organizations?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/isolation_segments/933b4c58-120b-499a-b85d-4b6fc9e2903b/organizations?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "name": "org1",
      "suspended": false,
      "links": {
        "self": {
          "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920"
        },
        "domains": {
          "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains"
        },
        "default_domain": {
          "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains/default"
        }
      },
      "relationships": {
        "quota": {
          "data": {
            "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
      "created_at": "2017-02-02T00:14:30Z",
      "updated_at": "2017-02-02T00:14:30Z",
      "name": "org2",
      "suspended": false,
      "relationships": {
        "quota": {
          "data": {
            "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
        },
        "domains": {
          "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains"
        },
        "default_domain": {
          "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains/default"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve the organizations entitled to the isolation segment. Return only the organizations the user has access to.

Definition

GET /v3/isolation_segments/:guid/organizations

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of organization names to filter by.
guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and name.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Auditor
Org Billing Manager
Org Manager

Update an organization

Example Request

curl "https://api.example.org/v3/organizations/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-organization" }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "suspended": false,
  "relationships": {
    "quota": {
      "data": {
        "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
    },
    "domains": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
    },
    "default_domain": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

PATCH /v3/organizations/:guid

Optional parameters

Name	Type	Description
name	string	Organization name
suspended (experimental)	boolean	Whether an organization is suspended or not.
metadata.labels (experimental)	label object	Labels applied to the organization.
metadata.annotations (experimental)	annotation object	Annotations applied to the organization.

Permitted roles

Admin
Org Manager

Delete an organization

Example Request

curl "https://api.example.org/v3/organizations/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/organizations/:guid

Permitted roles

Role	Notes
Admin

Assign default isolation segment

Example Request

curl "https://api.example.org/v3/organizations/[guid]/relationships/default_isolation_segment" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "guid": "[iso-seg-guid]"
     }
   }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment"
    },
    "related": {
      "href": "https://api.example.org/v3/isolation_segments/9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
    }
  }
}

Set the default isolation segment for a given organization. Only isolation segments that are entitled to the organization are eligible to be the default isolation segment.

Definition

PATCH /v3/organizations/:guid/relationships/default_isolation_segment

Required parameters

Name	Type	Description
data	to-one relationship	Isolation segment relationship. Apps will run in this isolation segment. Set data to null to remove the relationship.

Permitted roles

Admin
Org Manager

Get default isolation segment

Example Request

curl "https://api.example.org/v3/organizations/[guid]/relationships/default_isolation_segment" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment"
    },
    "related": {
      "href": "https://api.example.org/v3/isolation_segments/9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
    }
  }
}

Retrieve the default isolation segment for a given organization.

Definition

GET /v3/organizations/:guid/relationships/default_isolation_segment

Permitted roles

All Roles

Get default domain

Example Request

curl "https://api.example.org/v3/organizations/[guid]/domains/default" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Retrieve the default domain for a given organization.

Definition

GET /v3/organizations/:guid/domains/default

Permitted roles

Roles	Notes
Space Developer
Space Manager
Space Auditor
Org Auditor
Org Manager
Org Billing Manager	Can only view domains without an organization relationship.
Admin
Admin Read-Only
Global Auditor

Get usage summary

Example Request

curl "https://api.example.org/v3/organizations/[guid]/usage_summary" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "usage_summary": {
    "started_instances": 3,
    "memory_in_mb": 50
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/usage_summary"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
    }
  }
}

This endpoint retrieves the specified organization object’s memory and app instance usage summary.

Definition

GET /v3/organizations/:guid/usage_summary

Permitted roles

All Roles

Packages

A package is an application’s ‘source code’; either raw bits for your application or a pointer to these bits.

In Cloud Foundry, packages are staged to produce an executable Droplet. We currently support raw bits and Docker packages.

The package object

Example Package object

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

Name	Type	Description
type	string	Package type. Valid values are bits, docker.
data	object	Data for package type.
state	string	State of the package. Valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, EXPIRED.
guid	uuid	Unique identifier for the package.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the package.
metadata.annotations (experimental)	annotation object	Annotations applied to the package.

Bits package

A bits package is used to upload source code for an app to. The bits package will provide an upload link to which a zip file should be uploaded.

Name	Type	Description
type	string	bits
data.error	string	If an error occurs this field will contain the error message.
data.checksum.type	string	The checksum type, for example: sha256.
data.checksum.value	string	The checksum value. This will be populated after bits are uploaded.
state	string	State of the package. Valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, EXPIRED.
guid	uuid	Unique identifier for the package.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the package.
metadata.annotations (experimental)	annotation object	Annotations applied to the package.

Docker package

A Docker package references a Docker image from a registry.

Name	Type	Description
type	string	docker
data.image	string	The registry address of the image.
data.username	string	The username for the image’s registry.
data.password	string	The password for the image’s registry.
state	string	State of the package. Valid states are READY, FAILED, COPYING, EXPIRED.
guid	uuid	Unique identifier for the package.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the package.
metadata.annotations (experimental)	annotation object	Annotations applied to the package.

Create a package

Example Request (buildpack app)

curl "https://api.example.org/v3/packages" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "bits",
    "relationships": {
      "app": {
        "data": {
          "guid": "[guid]"
        }
      }
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "AWAITING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

Example Request (Docker app)

curl "https://api.example.org/v3/packages" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "docker",
    "relationships": {
      "app": {
        "data": {
          "guid": "[guid]"
        }
      }
    },
    "data": {
      "image": "registry/image:latest",
      "username": "username",
      "password": "password"
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "4cb65058-f04f-458f-aca1-5f4e43de6407",
  "type": "docker",
  "data": {
    "image": "registry/image:latest",
    "username": "username",
    "password": "***"
  },
  "state": "READY",
  "created_at": "2015-11-03T00:53:54Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/4cb65058-f04f-458f-aca1-5f4e43de6407"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/d8b8148d-5798-44de-821a-64b85b15e968"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/packages

Required parameters

Name	Type	Description
type	string	Type of the package. Valid values are bits, docker.
relationships.app	to-one relationship	A relationship to an app.

Optional parameters

Name	Type	Description	Default
data	object	Data for package type.	{}

Conditional Parameters

Name	Type	Description
data.image	string	Required when type is docker. The registry address of the image.
data.username	string	Optional when type is docker and accessing a secured registry.
data.password	string	Optional when type is docker and accessing a secured registry.
metadata.labels (experimental)	label object	Labels applied to the package.
metadata.annotations (experimental)	annotation object	Annotations applied to the package.

Permitted roles

Admin
Space Developer

Get a package

Example Request

curl "https://api.example.org/v3/packages/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

Definition

GET /v3/packages/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List packages

Example Request

curl "https://api.example.org/v3/packages" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "a57fd932-85db-483a-a27e-b00efbb3b0a4",
      "type": "bits",
      "data": {
        "checksum": {
          "type": "sha256",
          "value": null
        },
        "error": null
      },
      "state": "AWAITING_UPLOAD",
      "created_at": "2015-11-03T00:53:54Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4"
        },
        "upload": {
          "href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/upload",
          "method": "POST"
        },
        "download": {
          "href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/download",
          "method": "GET"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691",
      "type": "docker",
      "data": {
        "image": "registry/image:latest",
        "username": "username",
        "password": "***"
      },
      "state": "READY",
      "created_at": "2015-11-03T00:53:54Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/packages/8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve all packages the user has access to.

Definition

GET /v3/packages

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of package guids to filter by.
states	list of strings	Comma-delimited list of package states to filter by.
types	list of strings	Comma-delimited list of package types to filter by.
app_guids	list of strings	Comma-delimited list of app guids to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List packages for an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/packages" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "752edab0-2147-4f58-9c25-cd72ad8c3561",
      "type": "bits",
      "data": {
        "error": null,
        "checksum": {
          "type": "sha256",
          "value": null
        }
      },
      "state": "READY",
      "created_at": "2016-03-17T21:41:09Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561"
        },
        "upload": {
          "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/upload",
          "method": "POST"
        },
        "download": {
          "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/download",
          "method": "GET"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve packages for an app that the user has access to.

Definition

GET /v3/apps/:guid/packages

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of package guids to filter by.
states	list of strings	Comma-delimited list of package states to filter by.
types	list of strings	Comma-delimited list of package types to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a package

Example Request

curl "https://api.example.org/v3/packages/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

Definition

PATCH /v3/packages/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the package.
metadata.annotations (experimental)	annotation object	Annotations applied to the package.

Permitted roles

Admin
Space Developer

Delete a package

Example Request

curl "https://api.example.org/v3/packages/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/packages/:guid

Permitted Roles

Admin
Space Developer

Copy a package

Example Request

curl "https://api.example.org/v3/packages?source_guid=[guid]" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "relationships": {
      "app": {
        "data": {
          "guid": "[destination-app-guid]"
        }
      }
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "fec72fc1-e453-4463-a86d-5df426f337a3",
  "type": "docker",
  "data": {
    "image": "http://awesome-sauce.example.org"
  },
  "state": "COPYING",
  "created_at": "2016-03-17T21:41:09Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/36208a68-562d-4f51-94ea-28bd8553a271"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

This endpoint copies the bits of a source package to a target package.

Definition

POST /v3/packages?source_guid=:guid

Required query parameters

Name	Type	Description
source_guid	uuid	GUID of the source package to copy from.

Required parameters

Name	Type	Description
relationships.app	to-one relationship	A relationship to the destination app.

Permitted roles

Admin
Space Developer

Download package bits

Example Request

curl "https://api.example.org/v3/packages/[guid]/download" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 302 Found

You are being redirected.

This endpoint downloads the bits of an existing package.

When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits. If the client is automatically following redirects, then the OAuth token that was used to communicate with Cloud Controller will be replayed on the new redirect request. Some blobstores may reject the request in that case. Clients may need to follow the redirect without including the OAuth token.

Definition

GET /v3/packages/:guid/download

Permitted roles

Admin
Space Developer

Stage a package

Staging a package is accomplished by creating a build. See Create a build.

Upload package bits

Example Request

curl "https://api.example.org/v3/packages/[guid]/upload" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -F bits=@"package.zip" \
  -F resources='[{"path":"path/to/content.txt","size_in_bytes":123,"checksum": {"value": "b907173290db6a155949ab4dc9b2d019dea0c901"}},{"path":"path/to/code.jar","size_in_bytes":123,"checksum": {"value": "ff84f89760317996b9dd180ab996b079f418396f"}},{"path":"path/to/code.jar","size_in_bytes":123,"checksum": {"value": "ff84f89760317996b9dd180ab996b079f418396f"},"mode":"644"}]'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

This upload endpoint takes a multi-part form requests for packages of type bits. The request requires either a .zip file uploaded under the bits field or a list of resource match objects under the resources field. These field may be used together.

The resources field in the request accepts the v2 resources object format.

Definition

POST /v3/packages/:guid/upload

Optional parameters

Name	Type	Description	Default
bits	form field	A binary zip file containing the package bits.
resources	form field	Fingerprints of the application bits that have previously been pushed to Cloud Foundry, formatted as resource match objects.	[]

Permitted roles

Admin
Space Developer

Processes

Processes define the runnable units of an app. An app can have multiple process types, each with differing commands and scale. Processes for an app are defined by the buildpack used to stage the app and can be customized by including a Procfile in the application source.

Web process type

• By default, a newly created app will come with one instance of the web process and all other process types are scaled to zero
• Scale the web process to zero if it is not required for your app
• Unless otherwise specified, all routes will be mapped to the web process by default

The process object

Example Process object

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "relationships": {
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
      "method": "POST"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

Name	Type	Description
type	string	Process type. A unique identifier for processes belonging to an app.
command	string or null	The command used to start the process. Use null to revert to the buildpack-detected or procfile-provided start command.
instances	integer	The number of instances to run.
memory_in_mb	integer	The memory in MB allocated per instance.
disk_in_mb	integer	The disk in MB allocated per instance.
health_check	health check object	The health check to perform on the process.
relationships.revision (experimental)	to-one relationship	The app revision the process is currently running.
guid	uuid	Unique identifier for the process.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the process.
metadata.annotations (experimental)	annotation object	Annotations applied to the process.

The health check object

Example health check object

{
  "type": "port",
  "data": {
    "timeout": null
  }
}

Name	Type	Description
type	string	The type of health check to perform. Valid values are http, port, and process. Default is port.
data.timeout	integer	The duration in seconds that health checks can fail before the process is restarted.
data.invocation_timeout	integer	The timeout in seconds for individual health check requests for http and port health checks.
data.endpoint	string	The endpoint called to determine if the app is healthy. This key is only present for http health checks.

The process stats object

Example process stats object

{
  "type": "web",
  "index": 0,
  "state": "RUNNING",
  "usage": {
    "time": "2016-03-23T23:17:30.476314154Z",
    "cpu": 0.00038711029163348665,
    "mem": 19177472,
    "disk": 69705728
  },
  "host": "10.244.16.10",
  "instance_ports": [
    {
      "external": 64546,
      "internal": 8080
    }
  ],
  "uptime": 9042,
  "mem_quota": 268435456,
  "disk_quota": 1073741824,
  "fds_quota": 16384,
  "isolation_segment": "example_iso_segment",
  "details": null
}

Name	Type	Description
type	string	Process type. A unique identifier for processes belonging to an app.
index	integer	The zero-based index of running instances.
state	string	The state of the instance. Valid values are RUNNING, CRASHED, STARTING, DOWN.
usage.time	datetime	The time when the usage was requested.
usage.cpu	number	The current cpu usage of the instance.
usage.mem	integer	The current memory usage of the instance.
usage.disk	integer	The current disk usage of the instance.
host	string	The host the instance is running on.
instance_ports	object	JSON array of port mappings between the network-exposed port used to communicate with the app (external) and port opened to the running process that it can listen on (internal).
uptime	integer	The uptime in seconds for the instance.
mem_quota	integer	The maximum memory the instance is allowed to use.
disk_quota	integer	The maximum disk the instance is allowed to use.
fds_quota	integer	The maximum file descriptors the instance is allowed to use.
isolation_segment	string	The current isolation segment that the instance is running on. The value is null when the instance is not placed on a particular isolation segment.
details	string	Information about errors placing the instance. The value is null if there are no placement errors.

Get a process

Example Request

curl "https://api.example.org/v3/processes/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "relationships": {
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
      "method": "POST"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

Definition

GET /v3/processes/:guid
GET /v3/apps/:guid/processes/:type

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Get stats for a process

Example Request

curl "https://api.example.org/v3/processes/[guid]/stats" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resources": [
    {
      "type": "web",
      "index": 0,
      "state": "RUNNING",
      "usage": {
        "time": "2016-03-23T23:17:30.476314154Z",
        "cpu": 0.00038711029163348665,
        "mem": 19177472,
        "disk": 69705728
      },
      "host": "10.244.16.10",
      "instance_ports": [
        {
          "external": 64546,
          "internal": 8080
        }
      ],
      "uptime": 9042,
      "mem_quota": 268435456,
      "disk_quota": 1073741824,
      "fds_quota": 16384,
      "isolation_segment": "example_iso_segment",
      "details": null
    }
  ]
}

Definition

GET /v3/processes/:guid/stats
GET /v3/apps/:guid/processes/:type/stats

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List processes

Example Request

curl "https://api.example.org/v3/processes" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/processes?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/processes?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/processes?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
      "type": "web",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 5,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "health_check": {
        "type": "port",
        "data": {
          "timeout": null
        }
      },
      "relationships": {
        "revision": {
          "data": {
            "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
        },
        "scale": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
          "method": "POST"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
        }
      }
    },
    {
      "guid": "3fccacd9-4b02-4b96-8d02-8e865865e9eb",
      "type": "worker",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 1,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "health_check": {
        "type": "process",
        "data": {
          "timeout": null
        }
      },
      "relationships": {
        "revision": null
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
        },
        "scale": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/actions/scale",
          "method": "POST"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

Retrieve all processes the user has access to.

Definition

GET /v3/processes

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of process guids to filter by.
types	list of strings	Comma-delimited list of process types to filter by.
app_guids	list of strings	Comma-delimited list of app guids to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List processes for app

Example Request

curl "https://api.example.org/v3/apps/[guid]/processes" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
      "type": "web",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 5,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "health_check": {
        "type": "port",
        "data": {
          "timeout": null
        }
      },
      "relationships": {
        "revision": {
          "data": {
            "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
        },
        "scale": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
          "method": "POST"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
        }
      }
    },
    {
      "guid": "3fccacd9-4b02-4b96-8d02-8e865865e9eb",
      "type": "worker",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 1,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "health_check": {
        "type": "process",
        "data": {
          "timeout": null
        }
      },
      "relationships": {
        "revision": null
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
        },
        "scale": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/actions/scale",
          "method": "POST"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

Retrieves all processes belonging to an app.

Definition

GET /v3/apps/:guid/processes

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of process guids to filter by.
types	list of strings	Comma-delimited list of process types to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a process

Example Request

curl "https://api.example.org/v3/processes/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "command": "rackup",
    "metadata": {
      "labels": {
        "key": "value"
      },
      "annotations": {
        "note": "detailed information"
      }
    }
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "relationships": {
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
      "method": "POST"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

Definition

PATCH /v3/processes/:guid

Optional parameters

Name	Type	Description
command	string or null	The command used to start the process. Use null to revert to the buildpack-detected or procfile-provided start command.
health_check	health check object	The health check to perform on the process.
metadata.labels (experimental)	label object	Labels applied to the process.
metadata.annotations (experimental)	annotation object	Annotations applied to the process.

Permitted roles

Admin
Space Developer

Scale a process

Example Request

curl "https://api.example.org/v3/processes/[guid]/actions/scale" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "instances": 5,
    "memory_in_mb": 256,
    "disk_in_mb": 1024
  }'

Example Response

HTTP/1.1 202 OK
Content-Type: application/json

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "relationships": {
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
      "method": "POST"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

Definition

POST /v3/processes/:guid/actions/scale
POST /v3/apps/:guid/processes/:type/actions/scale

Optional parameters

Name	Type	Description
instances	integer	The number of instances to run.
memory_in_mb	integer	The memory in mb allocated per instance.
disk_in_mb	integer	The disk in mb allocated per instance.

Permitted roles

Admin
Space Developer

Terminate a process instance

Example Request

curl "https://api.example.org/v3/processes/[guid]/instances/[index]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

Terminate an instance of a specific process. Health management will eventually restart the instance.

This allows a user to stop a single misbehaving instance of a process.

Definition

DELETE /v3/processes/:guid/instances/:index
DELETE /v3/apps/:guid/processes/:type/instances/:index

Permitted Roles

Admin
Space Developer

Routes

Routes are addresses that direct matched network traffic to one or more destinations. Each route is based on a domain name with additional matching criteria (host (subdomain), path, etc). Matched traffic will be distributed across all destinations, based on their configuration (round-robin by default).

The route object

Example Route object

  {
    "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
    "host": "a-hostname",
    "path": "/some_path",
    "url": "a-hostname.a-domain.com/some_path",
    "created_at": "2019-05-10T17:17:48Z",
    "updated_at": "2019-05-10T17:17:48Z",
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
        }
      },
      "domain": {
        "data": {
          "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
        }
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
      },
      "space": {
        "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
      },
      "domain": {
        "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
      },
      "destinations": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
      }
    }
  }

Name	Type	Description
guid	uuid	Unique identifier for the route.
host	string	The hostname for the route. Must be under 63 character long and only contain letters, numbers, dashes (-) or underscores(_).
path	string	The path for the route. Must be under 128 character long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from RFC 2396.
url	string	The URL for the route. Combination of host, domain name, and path.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
space	to-one relationship	A relationship to the space containing the route. Routes can only be mapped to destinations in that space.
domain	to-one relationship	A relationship to the domain of the route.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the route.
metadata.annotations (experimental)	annotation object	Annotations applied to the route.

The destination object

Example Destination object

{
  "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
  "app": {
    "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
    "process": {
      "type": "web"
    }
  },
  "weight": null,
  "port": 8080
}

A destination represents the relationship between a route and a resource that can serve traffic (for example, the web process of an application).

When a route has destinations, that route will direct traffic to the processes represented by those destinations.

If a destination is created with a port specified, the route will direct traffic to that port on the process. A destination with port 9000 and process type api means traffic will be directed to the api process running on container port 9000.

Note that when using a custom port, the app process must be listening on the specified port for the mapping to work. Otherwise, visiting the route will result in a 404 error.

If a destination does not specify a port, the default port depends on the app lifecycle type. For buildpack apps, traffic will be directed to port 8080. For Docker apps, the first port specified in the Dockerfile will be used.

Name	Type	Description
guid	uuid	Unique identifier for the destination.
app.guid	uuid	Unique identifier for the app to route traffic to.
app.process.type	string	Type of the process belonging to the app to route traffic to.
port	integer	Port on the destination process to route traffic to.
weight (experimental)	integer or null	Percentage of traffic which will be routed to this destination. This feature is only available via the BETA Service Mesh routing plane.

Create a route

Example Request

curl "https://api.example.org/v3/routes" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "host": "a-hostname",
    "path": "/some_path",
    "relationships": {
      "domain": {
        "data": { "guid": "domain-guid" }
      },
      "space": {
        "data": { "guid": "space-guid" }
      }
    },
    "metadata": {
      "labels": { "key": "value" },
      "annotations": { "note": "detailed information"}
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
    "host": "a-hostname",
    "path": "/some_path",
    "url": "a-hostname.a-domain.com/some_path",
    "created_at": "2019-05-10T17:17:48Z",
    "updated_at": "2019-05-10T17:17:48Z",
    "metadata": {
      "labels": { "key": "value" },
      "annotations": { "note": "detailed information" }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
        }
      },
      "domain": {
        "data": {
          "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
        }
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
      },
      "space": {
        "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
      },
      "domain": {
        "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
      },
      "destinations": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
      }
    }
  }

Definition

POST /v3/routes

Required parameters

Name	Type	Description
relationships.space	to-one relationship	A relationship to the space containing the route. Routes can only be mapped to destinations in that space.
relationships.domain	to-one relationship	A relationship to the domain of the route.

Optional parameters

Name	Type	Description
host	string	The host component for the route.
path	string	The path component for the route. Should begin with a /.
metadata.annotations (experimental)	annotation object	Annotations applied to the route.
metadata.labels (experimental)	label object	Labels applied to the route.

Permitted roles

Role	Notes
Admin
Space Developer

Get a route

Example Request

curl "https://api.example.org/v3/routes/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
    "host": "a-hostname",
    "path": "/some_path",
    "url": "a-hostname.a-domain.com/some_path",
    "created_at": "2019-05-10T17:17:48Z",
    "updated_at": "2019-05-10T17:17:48Z",
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
        }
      },
      "domain": {
        "data": {
          "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
        }
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
      },
      "space": {
        "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
      },
      "domain": {
        "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
      },
      "destinations": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
      }
    }
  }

Definition

GET /v3/routes/:guid

Permitted roles

Role	Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List routes

Example Request

curl "https://api.example.org/v3/routes" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/routes?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/routes?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/routes?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
        "host": "a-hostname",
        "path": "/some_path",
        "url": "a-hostname.a-domain.com/some_path",
        "created_at": "2019-05-10T17:17:48Z",
        "updated_at": "2019-05-10T17:17:48Z",
        "metadata": {
          "labels": {},
          "annotations": {}
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
            }
          },
          "domain": {
            "data": {
              "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
            }
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
          },
          "space": {
            "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
          },
          "domain": {
            "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
          },
          "destinations": {
            "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
          }
        }
      }
    ]
  }

Retrieve all routes the user has access to.

Definition

GET /v3/routes

Query parameters

Name	Type	Description
hosts	list of strings	Comma-delimited list of hostnames to filter by.
paths	list of strings	Comma-delimited list of paths to filter by (e.g. /path1,/path2).
domain_guids	list of strings	Comma-delimited list of domain guids to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List routes for an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/routes" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
        "host": "a-hostname",
        "path": "/some_path",
        "url": "a-hostname.a-domain.com/some_path",
        "created_at": "2019-05-10T17:17:48Z",
        "updated_at": "2019-05-10T17:17:48Z",
        "metadata": {
          "labels": {},
          "annotations": {}
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
            }
          },
          "domain": {
            "data": {
              "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
            }
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
          },
          "space": {
            "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
          },
          "domain": {
            "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
          },
          "destinations": {
            "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
          }
        }
      }
    ]
  }

Retrieve all routes that have destinations that point to the given app.

Definition

GET /v3/apps/:guid/routes

Query parameters

Name	Type	Description
hosts	list of strings	Comma-delimited list of hostnames to filter by.
paths	list of strings	Comma-delimited list of paths to filter by (e.g. /path1,/path2).
domain_guids	list of strings	Comma-delimited list of domain guids to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a route

Example Request

curl "https://api.example.org/v3/routes/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "metadata": {
      "labels": {"key": "value"},
      "annotations": {"note": "detailed information"}
    }
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
    "host": "a-hostname",
    "path": "/some_path",
    "url": "a-hostname.a-domain.com/some_path",
    "created_at": "2019-05-10T17:17:48Z",
    "updated_at": "2019-05-10T17:17:48Z",
    "metadata": {
      "labels": { "key": "value" },
      "annotations": { "note": "detailed information" }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
        }
      },
      "domain": {
        "data": {
          "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
        }
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
      },
      "space": {
        "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
      },
      "domain": {
        "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
      },
      "destinations": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
      }
    }
  }

Definition

PATCH /v3/routes/:guid

Optional parameters

Name	Type	Description	Default
metadata.labels (experimental)	label object	Labels applied to the route.
metadata.annotations (experimental)	annotation object	Annotations applied to the route.

Permitted roles

Role	Notes
Admin
Space Developer

Delete a route

Example Request

curl "https://api.example.org/v3/routes/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/routes/:guid

Permitted roles

Role	Notes
Admin
Space Developer

Check reserved routes for a domain

Example Request

curl "https://api.example.org/v3/domains/[guid]/route_reservations" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  { "matching_route": true }

Check if a specific route for a domain exists, regardless of the user’s visibility for the route in case the route belongs to a space the user does not belong to.

Definition

GET /v3/domains/:guid/route_reservations

Query parameters

Name	Type	Description
host	string	Hostname to filter by. Defaults to empty string if not provided.
path	string	Path to filter by. Defaults to empty string if not provided.

Permitted roles

Role	Notes
Admin
Admin Read-Only
Global Auditor
Org Auditor
Org Billing Manager	Can only check if routes exist for a domain without an organization relationship.
Org Manager
Space Auditor
Space Developer
Space Manager

List destinations for a route

Example Request

curl "https://api.example.org/v3/routes/[guid]/destinations" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "destinations": [
      {
        "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
        "app": {
          "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
          "process": {
            "type": "web"
          }
        },
        "weight": null,
        "port": 8080
      },
      {
        "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "weight": null,
        "port": 9000
      }
    ],
    "links": {
      "self": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
      },
      "route": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
      }
    }
  }

Retrieve all destinations associated with a route.

Definition

GET /v3/routes/:guid/destinations

Permitted roles

Role	Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Insert destinations for a route

Example Request

curl "https://api.example.org/v3/routes/[guid]/destinations" \
  -X POST \
  -H "Authorization: bearer [token]"
  -d '{
    "destinations": [
      {
        "app": {
          "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
        }
      },
      {
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "port": 9000
      }
    ]
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "destinations": [
      {
        "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
        "app": {
          "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
          "process": {
            "type": "web"
          }
        },
        "weight": null,
        "port": 8080
      },
      {
        "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "weight": null,
        "port": 9000
      }
    ],
    "links": {
      "self": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
      },
      "route": {
        "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
      }
    }
  }

Add one or more destinations to a route, preserving any existing destinations.

Note that weighted destinations cannot be added with this endpoint. To add weighted destinations, replace all destinations for a route at once using the replace destinations endpoint.

Definition

POST /v3/routes/:guid/destinations

Required parameters

Name	Type	Description
destinations	array of destination objects	List of destinations to add to route. Destinations without process.type specified will get process type "web" by default.

Permitted roles

Role
Admin
Space Developer

Replace all destinations for a route

Example Request

curl "https://api.example.org/v3/routes/[guid]/destinations" \
  -X PATCH \
  -H "Authorization: bearer [token]"
  -d '{
    "destinations": [
      {
        "app": {
          "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
        },
        "weight": 61
      },
      {
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "weight": 39,
        "port": 9000
      }
    ]
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "destinations": [
    {
      "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
      "app": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
        "process": {
          "type": "web"
        }
      },
      "weight": 61,
      "port": 8080
    },
    {
      "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
      "app": {
        "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
        "process": {
          "type": "api"
        }
      },
      "weight": 39,
      "port": 9000
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
    },
    "route": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
    }
  }
}

Replaces all destinations for a route, removing any destinations not included in the provided list.

If using weighted destinations, all destinations provided here must have a weight specified, and all weights for this route must sum to 100. If not, all provided destinations must not have a weight. Mixing weighted and unweighted destinations for a route is not allowed.

Definition

PATCH /v3/routes/:guid/destinations

Required parameters

Name	Type	Description
destinations	array of destination objects	List of destinations use for route. Destinations without process.type specified will get process type "web" by default.

Permitted roles

Role
Admin
Space Developer

Remove destination for a route

Example Request

curl "https://api.example.org/v3/routes/[guid]/destinations/[destination_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

Remove a destination from a route.

Definition

DELETE /v3/routes/:guid/destinations/:destination_guid

Permitted roles

Role	Notes
Admin
Space Developer

Delete unmapped routes for a space

Example Request

curl "https://api.example.org/v3/spaces/[guid]/routes?unmapped=true" \
  -X DELETE\
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Deletes all routes in a space that are not mapped to any applications and not bound to any service instances.

Definition

DELETE /v3/spaces/:guid/routes?unmapped=true

Permitted roles

Role	Notes
Admin
Space Developer

Note: unmapped=true is a required query parameter; always include it.

Service Instances

An instantiation of a service offering.

The service instance object

Example Service Instance object

{
  "guid": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
  "created_at": "2017-11-17T13:54:21Z",
  "updated_at": "2017-11-17T13:54:21Z",
  "name": "my_service_instance",
  "relationships": {
    "space": {
      "data": {
        "guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "space": {
      "href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
    }
  }
}

Name	Type	Description
name	string	Name of the service instance.
guid	uuid	Unique identifier for the service instance.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
relationships.space	to-one relationship	The space the service instance is contained in.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the service instance.
metadata.annotations (experimental)	annotation object	Annotations applied to the service instance.

List service instances

Example Request

curl "https://api.example.org/v3/service_instances" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/service_instances?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/service_instances?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
      "created_at": "2017-11-17T13:54:21Z",
      "updated_at": "2017-11-17T13:54:21Z",
      "name": "my_service_instance",
      "relationships": {
        "space": {
          "data": {
            "guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
          }
        }
      },
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "links": {
        "space": {
          "href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
        }
      }
    }
  ]
}

This endpoint retrieves the service instances the user has access to. At the moment, this endpoint only returns managed service instances. This may change in the future.

This includes access granted by service instance sharing.

Definition

GET /v3/service_instances

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of service instance names to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List shared spaces relationship

Example Request

curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
    }
  }
}

This endpoint lists the spaces that the service instance has been shared to.

Definition

GET /v3/service_instances/:guid/relationships/shared_spaces

Permitted roles (in the service instance’s originating space)

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a service instance

Example Request

curl "https://api.example.org/v3/service_instances/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
  "created_at": "2017-11-17T13:54:21Z",
  "updated_at": "2017-11-17T13:54:21Z",
  "name": "my_service_instance",
  "relationships": {
    "space": {
      "data": {
        "guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
      }
    }
  },
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "links": {
    "space": {
      "href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
    }
  }
}

Definition

PATCH /v3/service_instances/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the service_instance.
metadata.annotations (experimental)	annotation object	Annotations applied to the service_instance.

Permitted roles

Admin
Space Developer

Share a service instance to other spaces

Example Request

curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"space-guid-1" },
      { "guid":"space-guid-2" }
    ]
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
    }
  }
}

This endpoint shares the service instance with the specified spaces. In order to share into a space the requesting user must be a space developer in the target space.

Definition

POST /v3/service_instances/:guid/relationships/shared_spaces

Required parameters

Name	Type	Description
data	to-many relationship	Shared space relationships. Each space will have this service instance shared to it.

Permitted roles

Admin
Space Developer

Unshare a service instance from another space

Example Request

curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces/[space_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

This endpoint unshares the service instance with the specified space. This will automatically unbind any applications bound to this service instance in the specified space.

Definition

DELETE /v3/service_instances/:guid/relationships/shared_spaces/:space_guid

Permitted roles

Admin
Space Developer

Spaces

Every application and service is scoped to a space. Each org contains at least one space. A space provides users with access to a shared location for application development, deployment, and maintenance.

The space object

Example Space object

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the space.
name	string	Name of the space.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
relationships.organization	to-one relationship	The organization the space is contained in.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the space.
metadata.annotations (experimental)	annotation object	Annotations applied to the space.

Create a space

Example Request

curl "https://api.example.org/v3/spaces" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-space",
    "relationships": {
      "organization": {
        "data": {
          "guid": "[org-guid]"
        }
      }
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/spaces

Required parameters

Name	Type	Description
name	string	Space name
relationships.organization	to-one relationship	A relationship to an organization.

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the space.
metadata.annotations (experimental)	annotation object	Annotations applied to the space.

Permitted roles

Admin
Org Manager

Get a space

Example Request

curl "https://api.example.org/v3/spaces/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

This endpoint retrieves the specified space object.

Definition

GET /v3/spaces/:guid

Query parameters

Name	Type	Description
include	string	Experimental - Optionally include additional related resources in the response. Valid value is org.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List spaces

Example Request

curl "https://api.example.org/v3/spaces" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/spaces?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/spaces?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "name": "space1",
      "relationships": {
        "organization": {
          "data": {
            "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
        },
        "organization": {
          "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
      "created_at": "2017-02-02T00:14:30Z",
      "updated_at": "2017-02-02T00:14:30Z",
      "name": "space2",
      "relationships": {
        "organization": {
          "data": {
            "guid": "b4ce91bd-31df-4b7d-8fd4-21a6b533276b"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
        },
        "organization": {
          "href": "https://api.example.org/v3/organizations/b4ce91bd-31df-4b7d-8fd4-21a6b533276b"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve all spaces the user has access to.

Definition

GET /v3/spaces

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of space names to filter by.
guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, name.
label_selector	string	Experimental - A query string containing a list of label selector requirements.
include	string	Experimental - Optionally include a list of unique related resources in the response. Valid value is org.

Permitted roles

All Roles

Update a space

Example Request

curl "https://api.example.space/v3/spaces/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "name": "new-space-name" }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

PATCH /v3/spaces/:guid

Optional parameters

Name	Type	Description
name	string	New space name
metadata.labels (experimental)	label object	Labels applied to the space.
metadata.annotations (experimental)	annotation object	Annotations applied to the space.

Permitted roles

Admin
Org Manager
Space Manager

Delete a space

Example Request

curl "https://api.example.org/v3/spaces/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/spaces/:guid

Permitted roles

Role	Notes
Admin
Org Manager

Get assigned isolation segment

Example Request

curl "https://api.example.org/v3/spaces/[guid]/relationships/isolation_segment" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment"
    },
    "related": {
      "href": "https://api.example.org/v3/isolation_segments/e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
    }
  }
}

Definition

GET /v3/spaces/:guid/relationships/isolation_segment

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Manage isolation segment

Example Request

curl "https://api.example.org/v3/spaces/[guid]/relationships/isolation_segment" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "guid": "[iso-seg-guid]"
    }
   }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment"
    },
    "related": {
      "href": "https://api.example.org/v3/isolation_segments/e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
    }
  }
}

This endpoint assigns an isolation segment to the space. The isolation segment must be entitled to the space’s parent organization.

Definition

PATCH /v3/spaces/:guid/relationships/isolation_segment

Required parameters

Name	Type	Description
data	to-one relationship	Isolation segment relationship. Apps will run in this isolation segment. Set data to null to remove the relationship.

Permitted roles

Admin
Org Manager

Stacks

Stacks are the base operating system and file system that your application will execute in. A stack is how you configure applications to run against different operating systems (like Windows or Linux) and different versions of those operating systems (like Windows 2012 or Windows 2016).

An application’s lifecycle will specify which stack to execute the application in. Buildpacks can also be associated with a particular stack if they contain stack-specific logic. An application will automatically use buildpacks associated with the application’s configured stack.

Stacks are not used for apps with a Docker lifecycle.

The stack object

Example Stack object

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Name	Type	Description
name	string	The name of the stack
description	string	The description of the stack
guid	uuid	Unique identifier for the stack.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
metadata.labels (experimental)	label object	Labels applied to the stack.
metadata.annotations (experimental)	annotation object	Annotations applied to the stack.
links	links object	Links to related resources.

Create a stack

Example Request

curl "https://api.example.org/v3/stacks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my-stack",
    "description": "Here is my stack!",
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

POST /v3/stacks

Required parameters

Name	Type	Description
name	string	Name of the stack. Must be unique and no longer than 250 characters.

Optional parameters

Name	Type	Description	Default
description	string	Description of the stack. Must no longer than 250 characters.	null
metadata.labels (experimental)	label object	Labels applied to the stack.
metadata.annotations (experimental)	annotation object	Annotations applied to the stack.

Permitted roles

Admin

Get a stack

Example Request

curl "https://api.example.org/v3/stacks/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

GET /v3/stacks/:guid

Permitted roles

All Roles

List stacks

Example Request

curl "https://api.example.org/v3/stacks" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/stacks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/stacks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/stacks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
      "created_at": "2018-11-09T22:43:28Z",
      "updated_at": "2018-11-09T22:43:28Z",
      "name": "my-stack-1",
      "description": "This is my first stack!",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
        }
      }
    },
    {
      "guid": "81c916c9-c2f9-440e-8e73-102e79c4704h",
      "created_at": "2018-11-09T22:43:29Z",
      "updated_at": "2018-11-09T22:43:29Z",
      "name": "my-stack-2",
      "description": "This is my second stack!",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/stacks/81c916c9-c2f9-440e-8e73-102e79c4704h"
        }
      }
    }
  ]
}

Retrieve all stacks.

Definition

GET /v3/stacks

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
names	list of strings	Comma-delimited list of app names to filter by.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

Update a stack

Example Request

curl "https://api.example.org/v3/stacks/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { "key": "value" },
     "annotations": { "note": "detailed information" }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

PATCH /v3/stacks/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the stack.
metadata.annotations (experimental)	annotation object	Annotations applied to the stack.

Permitted roles

Admin
Space Developer

Delete a stack

Example Request

curl "https://api.example.org/v3/stacks/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

Definition

DELETE /v3/stacks/:guid

Permitted roles

Admin

Tasks

Tasks are one-off jobs that are intended to perform a task, stop, and be cleaned up, freeing up resources.

Examples of this include database migrations, sending things, and batch jobs.

The task object

Example Task object

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Name	Type	Description
sequence_id	integer	User-facing id of the task. This number is unique for every task associated with a given app.
name	string	Name of the task.
command	string	Command that will be executed. This field may be excluded based on a user’s role.
disk_in_mb	integer	Amount of disk to allocate for the task in MB.
memory_in_mb	integer	Amount of memory to allocate for the task in MB.
state	string	State of the task. Possible states are PENDING, RUNNING, SUCCEEDED, CANCELING, and FAILED
droplet_guid	uuid	The guid of the droplet that will be used to run the command.
result	object	Results from the task
result.failure_reason	string	Null if the task succeeds, contains the error message if it fails.
guid	uuid	Unique identifier for the task.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the task.
metadata.annotations (experimental)	annotation object	Annotations applied to the task.

Create a task

Example Request with Command

curl "https://api.example.org/v3/apps/[guid]/tasks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "command": "rake db:migrate" }'

Example Request with Template Process

curl "https://api.example.org/v3/apps/[guid]/tasks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "template": { "process": {"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e"} } }'

Example Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Definition

POST /v3/apps/:guid/tasks

Required parameters

Name	Type	Description
command[1]	string	Command that will be executed. NOTE: optional if a template.process.guid is provided

Optional parameters

Name	Type	Description	Default
name	string	Name of the task.	auto-generated
disk_in_mb[1]	integer	Amount of disk to allocate for the task in MB.	operator-configured default_app_disk_in_mb
memory_in_mb[1]	integer	Amount of memory to allocate for the task in MB.	operator-configured default_app_memory
droplet_guid	uuid	The guid of the droplet that will be used to run the command.	the app’s current droplet
template.process.guid (experimental)	uuid	The guid of the process that will be used as a template.	null
metadata.labels (experimental)	label object	Labels applied to the package.
metadata.annotations (experimental)	annotation object	Annotations applied to the package.

^{1 If not provided, and a template.process.guid is provided, this field will use the value from the process with the given guid.}

Permitted roles

Admin
Space Developer

Get a task

Example Request

curl "https://api.example.org/v3/tasks/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Retrieve a specific task. The command field may be excluded in the response based on the user’s role.

Definition

GET /v3/tasks/:guid

Permitted roles

Admin Read-Only
Admin
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List tasks

Example Request

curl "https://api.example.org/v3/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/tasks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/tasks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/tasks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "sequence_id": 1,
      "name": "hello",
      "state": "SUCCEEDED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": null
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
    {
      "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
      "sequence_id": 2,
      "name": "migrate",
      "state": "FAILED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": "Exited with status 1"
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    }
  ]
}

Retrieve all tasks the user has access to. The command field is excluded in the response.

Definition

GET /v3/tasks

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of task guids to filter by.
names	list of strings	Comma-delimited list of task names to filter by.
states	list of strings	Comma-delimited list of task states to filter by.
app_guids	list of strings	Comma-delimited list of app guids to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List tasks for an app

Example Request

curl "https://api.example.org/v3/apps/:guid/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "sequence_id": 1,
      "name": "hello",
      "state": "SUCCEEDED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": null
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
    {
      "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
      "sequence_id": 2,
      "name": "migrate",
      "state": "FAILED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": "Exited with status 1"
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    }
  ]
}

Retrieve tasks for an app the user has access to. The command field may be excluded in the response based on the user’s role.

Definition

GET /v3/apps/:guid/tasks

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of task guids to filter by.
names	list of strings	Comma-delimited list of task names to filter by.
states	list of strings	Comma-delimited list of task states to filter by.
sequence_ids	list of strings	Comma delimited list of sequence ids to filter by. Valid values are integers >= 1
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin Read-Only
Admin
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a task

Example Request

curl "https://api.example.org/v3/tasks/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Definition

PATCH /v3/tasks/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the task.
metadata.annotations (experimental)	annotation object	Annotations applied to the task.

Permitted roles

Admin
Space Developer

Cancel a task

Example Request

curl "https://api.example.org/v3/tasks/[guid]/actions/cancel" \
  -X POST \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "CANCELING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Cancels a running task.

Canceled tasks will initially be in state CANCELING and will move to state FAILED once the cancel request has been processed.

Cancel requests are idempotent and will be processed according to the state of the task when the request is executed.

Canceling a task that is in SUCCEEDED or FAILED state will return an error.

Definition

POST /v3/tasks/:guid/actions/cancel
PUT /v3/tasks/:guid/cancel (Deprecated)

Permitted roles

Admin
Space Developer

Experimental Resources

App Features

The app feature object

Example App Feature object

{
  "name": "ssh",
  "description": "Enable SSHing into the app.",
  "enabled": true
}

Name	Type	Description
name	string	Name of the app feature.
description	string	Description of the app feature.
enabled	boolean	Denotes whether or not the app feature is enabled.

Supported app features

Name	Description
ssh	Enable SSHing into the app.
revisions	Enable versioning of an application (experimental)

Get an app feature

Example Request

curl "https://api.example.org/v3/apps/[guid]/features/[name]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "ssh",
  "description": "Enable SSHing into the app.",
  "enabled": true
}

Definition

GET /v3/apps/:guid/features/:name

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List app features

Example Request

curl "https://api.example.org/v3/apps/[guid]/features" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resources": [
    {
      "name": "ssh",
      "description": "Enable SSHing into the app.",
      "enabled": true
    },
    {
      "name": "revisions",
      "description": "Enable versioning of an application (experimental)",
      "enabled": false
    }
  ],
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
    "last": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
    "next": null,
    "previous": null
  }
}

This endpoint retrieves the list of features for the specified app.

Definition

GET /v3/apps/:guid/features

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update an app feature

Example Request

curl "https://api.example.org/v3/apps/[guid]/features/[name]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "enabled": false }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "ssh",
  "description": "Enable SSHing into the app.",
  "enabled": true
}

Definition

PATCH /v3/apps/:guid/features/:name

Required parameters

Name	Type	Description
enabled	boolean	Denotes whether or not the app feature should be enabled.

Permitted roles

Admin
Space Developer

App Manifest

The app manifest is a method for applying bulk configuration to an app and its underlying processes.

The app manifest specification

Example Manifest

---
applications:
- buildpacks:
    - ruby_buildpack
    - java_buildpack
  env:
    VAR1: value1
    VAR2: value2
  routes:
  - route: route.example.com
  - route: another-route.example.com
  services:
  - my-service1
  - my-service2
  - name: my-service-with-arbitrary-params
    parameters:
      key1: value1
      key2: value2
  stack: cflinuxfs3
  metadata:
    annotations:
      contact: "[email protected] [email protected]"
    labels:
      sensitive: true
  processes:
  - type: web
    command: start-web.sh
    disk_quota: 512M
    health-check-http-endpoint: /healthcheck
    health-check-type: http
    health-check-invocation-timeout: 10
    instances: 3
    memory: 500M
    timeout: 10
  - type: worker
    command: start-worker.sh
    disk_quota: 1G
    health-check-type: process
    instances: 2
    memory: 256M
    timeout: 15
  sidecars:
  - name: authenticator
    process_types: [ 'web', 'worker' ]
    command: bundle exec run-authenticator
    memory: 800M
  - name: upcaser
    process_types: [ 'worker' ]
    command: ./tr-server
    memory: 900M

App-level configuration

This configuration is specified at the top-level and applies to all of the app’s processes.

Field	Description
buildpacks	Must be an Array. a) An empty array, which will automatically select the appropriate default buildpack according to the coding language. b) An array of one or more URLs pointing to buildpacks. c) An array of one or more installed buildpack names. Replaces the legacy buildpack field.
env	A key-value hash of environment variables to be used for the app when running.
no-route	Boolean value. Removes the app’s routes if true; ignored if false. Cannot be used in conjunction with the routes attribute when set to true.
processes	List of configurations for individual process types. See Process-level configuration.
random-route	Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified.
routes	An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path
services	An array of service-instances to bind to the app. See Service-level configuration.
sidecars	An array of configurations for individual sidecars. See Sidecar-level configuration.
stack	The root filesystem to use with the buildpack, for example cflinuxfs3.
metadata.labels (experimental)	Labels applied to the app.
metadata.annotations (experimental)	Annotations applied to the app.
buildpack	DEPRECATED in favor of the buildpacks field above. a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language. b) A URL pointing to a buildpack. c) Name of an installed buildpack.

Process-level configuration

This configuration is for the individual process. Each process is created if it does not already exist.

With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.

If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.

Field	Description
type	(Required) Process type. The identifier for the processes to be configured.
command	The command used to start the process. This overrides start commands from Procfiles and buildpacks.
disk_quota	The disk limit for all instances of the web process. This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
health-check-http-endpoint	Endpoint called to determine if the app is healthy.
health-check-invocation-timeout	The timeout in seconds for individual health check requests for http and port health checks.
health-check-type	Type of health check to perform. none is deprecated and an alias to process.
instances	The number of instances to run.
memory	The memory limit for all instances of the web process. This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
timeout	Time in seconds at which the health-check will report failure.

Service-level configuration

This configuration is creating new service bindings between the app and a service instance. The services field can take either an array of service instance name strings or an array of the following service-level fields.

Field	Description
name	(Required) Service instance name. The name of the service instance to be bound to.
parameters	A map of arbitrary key/value pairs to send to the service broker during binding.

Sidecar-level configuration

This configuration is for the individual sidecar. Each sidecar is created if it does not already exist.

Field	Description
name	(Required) Sidecar name. The identifier for the sidecars to be configured.
command	The command used to start the sidecar.
process_types	List of processes to associate sidecar with.
memory	Memory in mb that the sidecar will be allocated.

Generate an app manifest

Example Request

curl "https://api.example.org/v3/apps/[guid]/manifest" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/x-yaml

---
applications:
- name: my-app
  stack: cflinuxfs3
  routes:
  - route: my-app.example.com
  processes:
  - type: web
    instances: 2
    memory: 512M
    disk_quota: 1024M
    health-check-type: port

Generate a manifest for an app and its underlying processes.

Definition

GET /v3/apps/:guid/manifest

Permitted Roles

Admin
Admin Read-Only
Space Developer

Apply an app manifest

Example Request

curl "https://api.example.org/v3/apps/[guid]/actions/apply_manifest" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/x-yaml" \
  --data-binary @/path/to/manifest.yml

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Apply changes specified in a manifest to an app and its underlying processes. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.

Definition

POST /v3/apps/:guid/actions/apply_manifest

Permitted Roles

Admin
Space Developer

App Restart

Restart an app

Example Request

curl "https://api.example.org/v3/apps/[guid]/actions/restart" \
-X POST \
-H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STARTED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-03-18T11:32:30Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
    },
    "current_droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
      "method": "POST"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
      "method": "POST"
    },
    "revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
    },
    "deployed_revisions": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/apps/:guid/actions/restart

Permitted roles

Admin
Space Developer

App SSH Enabled

Get app SSH enabled

Example Request

curl "https://api.example.org/v3/apps/:guid/ssh_enabled" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "enabled": false,
  "reason": "Disabled globally"
}

Definition

GET /v3/apps/:guid/ssh_enabled

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Deployments

Deployments are objects that manage updates to applications with zero downtime.

They can either:

• Manage updating an app’s droplet directly after an application package is staged

• Roll an app back to a specific revision along with its associated droplet

It is possible to use rolling deployments for applications without incurring downtime. This is different from the traditional method of pushing app updates which performs start/stop deployments.

The deployment object

Example Deployment object

{
  "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
  "state": "DEPLOYING",
  "status": {
    "value": "DEPLOYING",
    "reason": null
  },
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
    }
  }
}

Name	Type	Description
state	string	(deprecated) The state of the deployment. Valid values are DEPLOYING, DEPLOYED, CANCELING, or CANCELED. This field will be removed in the future; use the status fields to determine deployment state instead.
status.value	string	The current status of the deployment. Valid values are DEPLOYING, CANCELING, and FINALIZED (meaning finished, either successfully or not).
status.reason	string or null	The reason for the final status of the deployment. Valid values are DEPLOYED, CANCELED, SUPERSEDED (another deployment created for app before completion), DEGENERATE (the deployment was created incorrectly by the system). This attribute is only set if the deployment has status.value of FINALIZED. If the deployment is still in progress, this field will be set to null.
guid	uuid	Unique identifier for the deployment.
relationships.app	to-one relationship	The app the deployment is updating.
droplet	object	The droplet the deployment is transitioning the app to.
previous_droplet	object	The app’s current droplet before the deployment was created.
new_processes	array	List of processes created as part of the deployment
revision	object	The revision the deployment is transitioning the app to.
metadata.labels (experimental)	label object	Labels applied to the deployment.
metadata.annotations (experimental)	annotation object	Annotations applied to the deployment.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.

Create a deployment

Example Request with Droplet

curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "droplet": {
    "guid": "[droplet-guid]"
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "[app-guid]"
      }
    }
  }
}'

Example Request with Revision

curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "revision": {
    "guid": "[revision-guid]"
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "[app-guid]"
      }
    }
  }
}'

Example Response

HTTP/1.1 201 OK
Content-Type: application/json


{
  "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
  "state": "DEPLOYING",
  "status": {
    "value": "DEPLOYING",
    "reason": null
  },
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
    }
  }
}

When you create a new deployment you can either provide a specific droplet or revision to deploy. If no revision or droplet is provided, the droplet associated with the app is deployed.

Definition

POST /v3/deployments

Required parameters

Name	Type	Description
relationships.app	to-one relationship	The app to deploy a droplet for.

Optional parameters

Name	Type	Description	Default
droplet[1]	object	The droplet to deploy for the app. This will update the app’s current droplet to this droplet	The app’s current droplet
revision[1]	object	The revision whose droplet to deploy for the app. This will update the app’s current droplet to this droplet
metadata.labels (experimental)	label object	Labels applied to the deployment.
metadata.annotations (experimental)	annotation object	Annotations applied to the deployment.

^{1 Only a droplet or a revision may be provided, not both.}

Permitted roles

Admin
Space Developer

Get a deployment

Example Request

curl "https://api.example.org/v3/deployments/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
  "state": "DEPLOYING",
  "status": {
    "value": "DEPLOYING",
    "reason": null
  },
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
    }
  }
}

Definition

GET /v3/deployments/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List deployments

Example Request

curl "https://api.example.org/v3/deployments" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/deployments?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/deployments?page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
      "state": "DEPLOYED",
      "status": {
        "value": "FINALIZED",
        "reason": "DEPLOYED"
      },
      "droplet": {
        "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
      },
      "previous_droplet": {
        "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
      },
      "new_processes": [
        {
          "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
          "type": "web-deployment-59c3d133-2b83-46f3-960e-7765a129aea4"
        }
      ],
      "revision": {
        "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
        "version": 1
      },
      "created_at": "2018-04-25T22:42:10Z",
      "updated_at": "2018-04-25T22:42:10Z",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "relationships": {
        "app": {
          "data": {
            "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
        }
      }
    }
  ]
}

Retrieve all deployments the user has access to.

Definition

GET /v3/deployments

Query parameters

Name	Type	Description
app_guids	list of strings	Comma-delimited list of app guids to filter by.
states	list of strings	Comma-delimited list of states to filter by.
status_reasons	list of strings	Comma-delimited list of status reasons to filter by. Valid values include DEPLOYED, CANCELED, SUPERSEDED, and a blank value.
status_values	list of strings	Comma-delimited list of status values to filter by. Valid values include DEPLOYING and FINALIZED.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin Read-Only
Admin
Global Auditor
Org Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a deployment

Example Request

curl "https://api.example.org/v3/deployments/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
  "state": "DEPLOYING",
  "status": {
    "value": "DEPLOYING",
    "reason": null
  },
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
    }
  }
}

Definition

PATCH /v3/deployments/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the deployment.
metadata.annotations (experimental)	annotation object	Annotations applied to the deployment.

Permitted roles

Admin
Space Developer

Cancel a deployment

Example Request

curl "https://api.example.org/v3/deployments/[guid]/actions/cancel" \
  -X POST \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

Definition

POST /v3/deployments/:guid/actions/cancel

Permitted roles

Admin
Space Developer

Resource Matches

This endpoint matches given resource SHA-1 / file size pairs against the Cloud Controller cache, and reports the subset that describes already cached files. This is usually used to avoid uploading duplicate files when pushing an app which has only been partially changed. The path and mode fields are not used when matching.

When uploading package bits, the response from this endpoint should be used as the resources form field. As such, it is useful to include the path and mode fields for each resource even though they are not used when determining a resource match.

Cloud Foundry operators may set minimum / maximum file sizes to match against. If the file size provided is outside this range, it will not be matched against.

The resource match object

Example Resource Match object

{
  "resources": [
    {
      "checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
      "size_in_bytes": 1,
      "path": "path/to/file",
      "mode": "644"
    }
  ]
}

Name	Type	Description
checksum.value	string	(Required) SHA-1 hash of file
size_in_bytes	integer	(Required) Size of file in bytes
path	string	Path to the file, relative to app root
mode	string	File mode, i.e. POSIX file permissions. Defaults to 0744

Create a resource match

Example Request

curl "https://api.example.org/v3/resource_matches" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
        "resources": [
          {
            "checksum": { "value": "002d760bea1be268e27077412e11a320d0f164d3" },
            "size_in_bytes": 36,
            "path": "C:\\path\\to\\file",
            "mode": "645"
          },
          {
            "checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
            "size_in_bytes": 1,
            "path": "path/to/file",
            "mode": "644"
          }
        ]
      }'

Example Response

HTTP/1.1 201 OK
Content-Type: application/json

{
  "resources": [
    {
      "checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
      "size_in_bytes": 1,
      "path": "path/to/file",
      "mode": "644"
    }
  ]
}

This endpoint returns a list of cached resources from the input list.

Definition

POST /v3/resource_matches

Required parameters

Name	Type	Description
resources	array of resource_object	List of resources to check for in the resource cache

Permitted roles

All Roles

Revisions

Revisions represent code used by an application at a specific time. The most recent revision for a running application represents code and configuration currently running in Cloud Foundry.

Revision are created when the following is changed:

• A new droplet is created for an app

• An app’s environment variables are changed

• The custom start command for an app is added or changed

• An app rolls back to a prior revision

Each time a new revision is created the reason(s) for the revisions creation will be appended to its description field.

By default the cloud foundry API retains at most 100 revisions per app.

The revision object

Example Revision object

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the revision.
version	integer	Human-readable identifier for the revision. Starts at 1, increments by 1 for each new revision of the app, and rolls back over to 1 at 9999.
droplet	object	The droplet used by a process running the revision.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
description	string	A short description of the reason for revision.
metadata.labels (experimental)	label object	Labels applied to the revision.
metadata.annotations (experimental)	annotation object	Annotations applied to the revision.
links	links object	Links to related resources.

Get a revision

Example Request

curl "https://api.example.org/v3/revisions/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
    }
  }
}

Definition

GET /v3/revisions/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List revisions for an app

Example Request

curl "https://api.example.org/v3/apps/:guid/revisions" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "version": 1,
      "droplet": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      },
      "description": "Initial revision.",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
        },
        "environment_variables": {
          "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
        }
      }
    }
  ]
}

Retrieve revisions for an app the user has access to.

Definition

GET /v3/apps/:guid/revisions

Query parameters

Name	Type	Description
versions	list of strings	Comma-delimited list of revision versions to filter by.
label_selector	string	Experimental - A query string containing a list of label selector requirements.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List deployed revisions for an app

Example Request

curl "https://api.example.org/v3/apps/:guid/revisions/deployed" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "version": 1,
      "droplet": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      },
      "description": "Initial revision.",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
        },
        "environment_variables": {
          "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
        }
      }
    }
  ]
}

Retrieve deployed revisions for an app the user has access to. Deployed revisions are revisions that are linked to started processes in the app.

Definition

GET /v3/apps/:guid/revisions/deployed

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a revision

Example Request

curl "https://api.example.org/v3/revisions/[revguid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
    }
  }
}

Definition

PATCH /v3/revisions/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the revision.
metadata.annotations (experimental)	annotation object	Annotations applied to the revision.

Permitted roles

Admin
Space Developer

Service Bindings

Service bindings are relations between a service instance and an app; to use a service instance with an app, you must first bind them together.

Not all services support binding, as some services deliver value to users directly without integration with an application.

The service binding object

Example Service Binding object

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Name	Type	Description
type	string	Service binding type. Valid value is app.
data	object	Data returned from the service broker for the service instance. Valid values are credentials, syslog_drain_url and (experimental) volume_mounts.
guid	uuid	Unique identifier for the service binding.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.

Create a service binding

Example Request

curl "https://api.example.org/v3/service_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "app",
    "relationships": {
      "app": {
        "data": {
          "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      },
      "service_instance": {
        "data": {
          "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
        }
      }
    },
    "data": {
      "parameters": {
        "some_object_id": "for_the_service_broker"
      }
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Definition

POST /v3/service_bindings

Required parameters

Name	Type	Description
type	string	Service binding type. Valid value is app.
relationships.app	to-one relationship	A relationship to an app.
relationships.service_instance	to-one relationship	A relationship to a service_instance.

Optional parameters

Name	Type	Description	Default
data.parameters	object	Additional configuration parameters for the service binding.	{}

Permitted roles

Admin
Space Developer

Get a service binding

Example Request

curl "https://api.example.org/v3/service_bindings/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Definition

GET /v3/service_bindings/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List service bindings

Example Request

curl "https://api.example.org/v3/service_bindings" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_bindings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "type": "app",
      "data": {
        "credentials": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "syslog_drain_url": "syslog://drain.url.example.org",
        "volume_mounts": []
      },
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        },
        "service_instance": {
          "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      }
    },
    {
      "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
      "type": "app",
      "data": {
        "credentials": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "syslog_drain_url": "syslog://drain.url.example.org",
        "volume_mounts": []
      },
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "service_instance": {
          "href": "https://api.example.org/v3/service_instances/8bf356j3-9e18-45b1-3333-124163f31f9e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      }
    }
  ]
}

This endpoint retrieves the service bindings the user has access to.

Definition

GET /v3/service_bindings

Query parameters

Name	Type	Description
app_guids	list of strings	Comma-delimited list of app guids to filter by.
service_instance_guids	list of strings	Comma-delimited list of service_instance guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

All Roles

Delete a service binding

Example Request

curl "https://api.example.org/v3/service_bindings/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

Definition

DELETE /v3/service_bindings/:guid

Permitted Roles

Admin
Space Developer

Service Brokers

Service brokers manage the lifecycle of services. On behalf of users, Cloud Controller will interact with service brokers to provision, get access to and manage access to the services and plans they offer.

The service broker object

Example Service Broker object

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "name": "my_service_broker",
  "url": "https://example.service-broker.com",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the service broker.
name	string	Name of the service broker.
url	string	URL of the service broker.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.

Get a service broker

Example Request

curl "https://api.example.org/v3/service_brokers/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "name": "my_service_broker",
  "url": "https://example.service-broker.com",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

This endpoint retrieves the service broker by GUID.

Definition

GET /v3/service_brokers/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Space Developer

List service brokers

Example Request

curl "https://api.example.org/v3/service_brokers" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_brokers?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "name": "my_service_broker",
      "url": "https://example.service-broker.com",
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "relationships": {} ,
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        }
      }
    },
    {
      "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
      "name": "another_service_broker",
      "url": "https://another-example.service-broker.com",
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "relationships": {
        "space": {
          "data": {
            "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_brokers/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  ]
}

This endpoint retrieves the service brokers the user has access to.

Definition

GET /v3/service_brokers

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of service broker names to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
space_guids	list of strings	Comma-delimited list of space GUIDs to filter by.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, name.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Space Developer

Create a service broker

Example Request

curl "https://api.example.org/v3/service_brokers" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_service_broker",
    "url": "https://example.service-broker.com",
    "credentials": {
      "type": "basic",
      "data": {
        "username": "us3rn4me",
        "password": "p4ssw0rd"
      }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "name": "my_service_broker",
  "url": "https://example.service-broker.com",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

This endpoint creates a new service broker.

Definition

POST /v3/service_brokers

Required parameters

Name	Type	Description
name	string	Name of the service broker.
url	string	URL of the service broker.
credentials	credentials	Credentials used to authenticate against the service broker.

Optional parameters

Name	Type	Description	Default
space	to-one relationship	If set, restricts broker visibility to the specified space.	null

The credentials object

Name	Type	Description
type	string	Type of the authentication mechanisms that can be used. Valid value is basic.
data	object	Data is used to hold the actual credentials depending on the authentication mechanism.

Example basic credentials

{
  "type": "basic",
  "data": {
    "username": "admin",
    "password": "secretpassw0rd"
  }
}

Basic credentials data

Name	Type	Description
username	string	The username with which to authenticate against the service broker.
password	string	The password with which to authenticate against the service broker.

Permitted roles

Space Developer
Admin

Sidecars

Sidecars are additional operating system processes that are run in the same container as a process.

Use cases for sidecars

Sidecars are useful for any app processes that need to communicate with another within the same container or are otherwise dependent on each other. Some use cases are:

• Two or more processes that require access to a shared file
• An Application Performance Monitoring (APM) tool that attaches to a dependent app’s processes
• Two or more processes that communicate via a local socket

Steps to create a sidecar

The recommended way to create sidecars for your app is with an app manifest.

 sidecars:
  - name: authenticator
    process_types: [ 'web', 'worker' ]
    command: bundle exec run-authenticator
  - name: performance monitor
      process_types: [ 'web' ]
      command: bundle exec run-performance-monitor
      memory: 128M

• name is a user defined identifier (unique per app)
• process_types is a list of app processes the sidecar will attach to. You can attach multiple sidecars to each process type your app uses
• command is the command used to start the sidecar
• memory is the memory reserved for the sidecar^[1]

^{1 Applies for Java apps. If you do not reserve memory for the sidecar, the JVM will consume all of the memory in the app container. This value must be less thatn the process’ reserved memory.}

Current limitations

• Start and stop order of app processes and their sidecars is undefined
• App processes and sidecar processes are codependent: if either crashes or exits, the other will as well
• Sidecars are currently not independently scalable (memory / disk) and share resources with the main app process and other sidecars within that container
• Sidecars only support PID based health checks; HTTP health-checks for sidecars are not currently supported
• This has only been tested on Linux based systems

The sidecar object

Example Sidecar object

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Name	Type	Description
guid	uuid	Unique identifier for the sidecar.
name	string	Human-readable name for the sidecar.
command	string	The command used to start the sidecar.
process_types	array of strings	A list of process types the sidecar applies to.
memory_in_mb	integer	Reserved memory for sidecar.
relationships.app	to-one relationship	The app the sidecare is associated with.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.

Create a sidecar associated with an app

Example Request

curl "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/sidecars" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "auth-sidecar",
    "command": "bundle exec rackup",
    "process_types": ["web", "worker"],
    "memory_in_mb": 300
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

POST /v3/apps/:guid/sidecars

Required parameters

Name	Type	Description
name	string	Human-readable name for the sidecar.
command	string	The command used to start the sidecar.
process_types	array of strings	A list of process types the sidecar applies to.

Optional parameters

Name	Type	Description
memory_in_mb	integer	Reserved memory for sidecar.

Permitted roles

Admin
Space Developer

Get a sidecar

Example Request

curl "https://api.example.org/v3/sidecars/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

GET /v3/sidecars/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a sidecar

Example Request

curl "https://api.example.org/v3/sidecars/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auth-sidecar",
    "command": "bundle exec rackup",
    "process_types": ["web", "worker"],
    "memory_in_mb": 300
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

PATCH /v3/sidecars/:guid

Optional parameters

Name	Type	Description
name	string	Human-readable name for the sidecar.
command	string	The command used to start the sidecar.
process_types	array of strings	A list of process types the sidecar applies to.
memory_in_mb	integer	Reserved memory for sidecar.

Permitted roles

Admin
Space Developer

List sidecars for app

Example Request

curl "https://api.example.org/v3/apps/[guid]/sidecars" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "name": "auth-sidecar",
      "command": "bundle exec rackup",
      "process_types": ["web", "worker"],
      "memory_in_mb": 300,
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z"
    },
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
      "name": "echo-sidecar",
      "command": "start-echo-server",
      "process_types": ["web"],
      "memory_in_mb": 300,
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:59Z",
      "updated_at": "2017-02-01T01:33:59Z"
    }
  ]
}

Retrieves all sidecars associated with a app.

Definition

GET /v3/apps/:guid/sidecars

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List sidecars for process

Example Request

curl "https://api.example.org/v3/processes/[guid]/sidecars" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "name": "auth-sidecar",
      "command": "bundle exec rackup",
      "process_types": ["web", "worker"],
      "memory_in_mb": 300,
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z"
    },
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
      "name": "echo-sidecar",
      "command": "start-echo-server",
      "process_types": ["web"],
      "memory_in_mb": 300,
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:59Z",
      "updated_at": "2017-02-01T01:33:59Z"
    }
  ]
}

Retrieves all sidecars associated with a process.

Definition

GET /v3/processes/:guid/sidecars

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Delete a sidecar

Example Request

curl "https://api.example.org/v3/sidecars/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

Definition

DELETE /v3/sidecars/:guid

Permitted roles

Admin
Space Developer

Space Manifest

The space manifest is a method for applying bulk configurations to apps and their underlying processes.

The space manifest specification

Example Manifest

---
applications:
- name: app1
  buildpacks:
  - ruby_buildpack
  - java_buildpack
  env:
    VAR1: value1
    VAR2: value2
  routes:
  - route: route.example.com
  - route: another-route.example.com
  services:
  - my-service1
  - my-service2
  - name: my-service-with-arbitrary-params
    parameters:
      key1: value1
      key2: value2
  stack: cflinuxfs3
  metadata:
    annotations:
      contact: "[email protected] [email protected]"
    labels:
      sensitive: true
  processes:
  - type: web
    command: start-web.sh
    disk_quota: 512M
    health-check-http-endpoint: /healthcheck
    health-check-type: http
    health-check-invocation-timeout: 10
    instances: 3
    memory: 500M
    timeout: 10
  - type: worker
    command: start-worker.sh
    disk_quota: 1G
    health-check-type: process
    instances: 2
    memory: 256M
    timeout: 15
- name: app2
  env:
    VAR1: value1
  processes:
  - type: web
    instances: 1
    memory: 256M
  sidecars:
  - name: authenticator
    process_types: [ 'web', 'worker' ]
    command: bundle exec run-authenticator
    memory: 800M

  - name: upcaser
    process_types: [ 'worker' ]
    command: ./tr-server
    memory: 2G

Space-level configuration

Field	Description
applications	An array of App configurations

App-level configuration

This configuration is specified at the top-level and applies to all of the app’s processes.

Field	Description
buildpacks	Must be an Array. a) An empty array, which will automatically select the appropriate default buildpack according to the coding language. b) An array of one or more URLs pointing to buildpacks. c) An array of one or more installed buildpack names. Replaces the legacy buildpack field.
docker	If present, the created app will have Docker lifecycle type. The value of this key is ignored by the API but may be used by clients to source the registry address of the image and credentials, if needed. The generate manifest endpoint will return the registry address of the image and username provided with this key.
env	A key-value hash of environment variables to be used for the app when running.
no-route	Boolean value. Removes the app’s routes if true; ignored if false. Cannot be used in conjunction with the routes attribute when set to true.
processes	List of configurations for individual process types. See Process-level configuration.
random-route	Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified.
routes	An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path
services	An array of service-instances to bind to the app. See Service-level configuration.
sidecars	An array of configurations for individual sidecars. See Sidecar-level configuration.
stack	The root filesystem to use with the buildpack, for example cflinuxfs3.
metadata.labels (experimental)	Labels applied to the app.
metadata.annotations (experimental)	Annotations applied to the app.
buildpack	DEPRECATED in favor of the buildpacks field above. a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language. b) A URL pointing to a buildpack. c) Name of an installed buildpack.

Process-level configuration

This configuration is for the individual process. Each process is created if it does not already exist.

With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.

If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.

Field	Description
type	(Required) Process type. The identifier for the processes to be configured.
command	The command used to start the process. This overrides start commands from Procfiles and buildpacks.
disk_quota	The disk limit for all instances of the web process. This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
health-check-http-endpoint	Endpoint called to determine if the app is healthy.
health-check-invocation-timeout	The timeout in seconds for individual health check requests for http and port health checks.
health-check-type	Type of health check to perform. none is deprecated and an alias to process.
instances	The number of instances to run.
memory	The memory limit for all instances of the web process. This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
timeout	Time in seconds at which the health-check will report failure.

Service-level configuration

This configuration is creating new service bindings between the app and a service instance. The services field can take either an array of service instance name strings or an array of the following service-level fields.

Field	Description
name	(Required) Service instance name. The name of the service instance to be bound to.
parameters	A map of arbitrary key/value pairs to send to the service broker during binding.

Sidecar-level configuration

This configuration is for the individual sidecar. Each sidecar is created if it does not already exist.

Field	Description
name	(Required) Sidecar name. The identifier for the sidecars to be configured.
command	The command used to start the sidecar.
process_types	List of processes to associate sidecar with.
memory	Memory in mb that the sidecar will be allocated.

Apply a space manifest

Example Request

curl "https://api.example.org/v3/spaces/[guid]/actions/apply_manifest" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/x-yaml" \
  --data-binary @/path/to/manifest.yml

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Apply changes specified in a manifest to the named apps and their underlying processes. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.

Definition

POST /v3/spaces/:guid/actions/apply_manifest

Query parameters

Name	Type	Description
no_route	boolean	Unmaps all existing routes and blocks route creation for apps in the manifest.

Permitted roles

Admin
Space Developer

Users

Every Cloud Foundry action (pushing an application, creating a space) requires a user. Each Cloud Foundry installation has one pre-installed user, admin, which can create subsequent users. Users can be assigned roles which give them privileges to perform actions. For example, the Space Developer role grants a user permission to manage apps and services in a space (to push apps, scale apps, delete apps).

The user object

Example User object

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Name	Type	Description
guid	uuid	Unique identifier for the user.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
username	string	The name registered in UAA. Will be null for UAA clients and non-UAA users.
presentation_name	string	The name displayed for the user. For UAA users, this is the same as the username. For UAA clients, this is the UAA client ID.
origin	string	The identity provider for the UAA user. Will be null for UAA clients.
links	links object	Links to related resources.

Create a user

Creating a user requires one value, a GUID. This creates a user in the Cloud Controller database.

Generally, the GUID should match the GUID of an already-created user in the UAA database, though this is not required.

Example Request

curl "https://api.example.org/v3/users" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

POST /v3/users

Required parameters

Name	Type	Description
guid	string	Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user’s GUID. In the case of UAA clients, this will match the UAA client ID.

Permitted roles

Role	Notes
Admin

List users

Example Request

curl "https://api.example.org/v3/users" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/users?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/users?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/users?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
     {
      "guid": "client_id",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "username": null,
      "presentation_name": "client_id",
      "origin": null,
      "links": {
        "self": {
          "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
        }
      }
    },
    {
      "guid": "9da93b89-3f89-4f05-7238-8a2b123c79l9",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "username": "some-name",
      "presentation_name": "some-name",
      "origin": "uaa",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9"
        }
      }
    }
  ]
}

Retrieve all users that the current user can see. For users without the admin or admin_read_only roles, this will just return the current user.

Definition

GET /v3/users

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.

Permitted roles

All Roles

Get a user

Example Request

curl "https://api.example.org/v3/users/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

GET /v3/users/:guid

Permitted roles

Admin
Admin Read-Only

Note: A user can always see themselves with this endpoint, regardless of role.

Delete a user

Example Request

curl "https://api.example.org/v3/users/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/users/:guid

Permitted roles

Role	Notes
Admin