Introduction

Overview

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

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

Getting help

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

We recommend reaching out to Slack first as we will be most responsive there.

More resources

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

Concepts

API Resource

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

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

See Resources and Experimental Resources for specific resources.

Required fields

Example Person Resource

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

  "name": "Bob",

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

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

Links

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

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

The link object

Example Link object

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

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

Authentication

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

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

Authorization

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

OAuth2 scopes

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

Cloud Foundry user roles

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

Errors

Example Error

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

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

The error object

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

Filters

Endpoints which return lists of resources also support filtering the returned resources using query parameters. The available filter parameters are described in a resource’s “list” endpoint in the section “Query parameters”.

Examples

Single value request

GET /v3/apps?names=the_name

This will return all apps with name the_name.

Multiple value request

GET /v3/apps?names=first_name,second_name

This will return all apps with name the_name OR second_name.

Multiple value request #2

GET /v3/spaces?label_selector=production,east_coast

This will return all spaces whose metadata has labels with keys production AND east_coast.

Combined filters

GET /v3/apps?names=the_name&stacks=cflinuxfs3

This will return all apps with name the_name AND stack cflinuxfs3.

Empty filters

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

GET /v3/buildpacks?stacks=

This will return all buildpacks with stack NULL.

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

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

Include

The include parameter allows clients to fetch resources and include information of parent objects in the response. For example, a response to /v3/spaces/:guid?include=organization will contain detailed information about the space and its parent organization.

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

Resources with includes

The following resources can take an include parameter:

Resource	Allowed values
apps	space.organization, space
apps/[:guid]	space.organization, space
roles	user, space, organization
roles/[:guid]	user, space, organization
routes	domain
routes/[:guid]	domain
spaces	organization
spaces/[:guid]	organization

Sample requests

Example request to apps resource to include parent orgs and spaces

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

Example response

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

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

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

Example response

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

Example request for all spaces including their parent organizations

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

    Example Response

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

Lifecycles

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

The lifecycle object

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

Buildpack lifecycle

Example Buildpack Lifecycle

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

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

Buildpack lifecycle object

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

Docker lifecycle

Example Docker Lifecycle

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

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

Docker lifecycle object

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

Metadata

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

Annotations

Example Resource with Annotations

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

  "name": "api-server",

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

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

Annotations are user-specified key-value pairs that are attached to API Resources. They do not affect the operation of Cloud Foundry. Annotations cannot be used in filters.

Examples may include (but are not limited to):

• "contact info": "[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 ( [a-z0-9A-Z] ) , -, _, and .
• Must begin and end with an alphanumeric character

Annotation value

Annotation values must adhere to the following restrictions:

• Length: 0-5000 unicode characters

Labels and selectors

Example Resource with Labels

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

  "name": "api-server",

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

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

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

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

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

Labels

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

Examples may include (but are not limited to):

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

Label keys

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

A label key prefix must adhere to the following restrictions:

• Length: 0-253 characters
• Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, and .
• DNS subdomain format (series of subdomain labels separated by .)

A label key name must adhere to the following restrictions:

• Length: 1-63 characters
• Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, _, and .
• Must begin and end with an alphanumeric character

Label values

Label values must adhere to the following restrictions:

• Length: 0-63 characters
• Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, _, and .
• Must begin and end with an alphanumeric character
• Empty values are allowed

Selectors

Example label selector

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

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

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

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

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

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

See the metadata documentation for more information.

Updating labels and annotations

Example Initial Metadata

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

Example Patch Request Body

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

Example Final Metadata

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

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

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

• To create, include the new key with a value
• To change, include the existing key with a new value
• To delete, include the existing key with a 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. For example, an app has a relationship to a space (every app belongs in one space); a space has a relationship with an organization (every space belongs in one organization).

Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not.

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

Many endpoints return the status of its relationships. For example, GET /v3/spaces/:guid returns a JSON response with a relationships key with the GUID of the organization to which the space belongs.

The relationship object

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

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

To-one relationships

Example to-one relationship

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

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

To-one relationship object

Name	Type	Description
data	relationship object	A single relationship

Setting the to-one relationship while creating an object

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

Modifying the to-one relationship

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

Removing the to-one relationship

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

Viewing the to-one relationship

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

To-many relationships

Example to-many relationship

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

Some relationships relate a resource to several other resources. For example, an isolation segment can be entitled to multiple organizations.

To-many relationship object

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

Adding related to-many resources

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

Replacing all to-many relationships

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

Removing all to-many relationships

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

Removing specific to-many relationships

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

Viewing the to-many relationships

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

Status Codes

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

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

Resources

Apps

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

The app object

Example App object

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

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

Create an app

Example Request

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

Example Response

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

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

Definition

POST /v3/apps

Required parameters

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Get an app

Example Request

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

Example Response

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

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

Definition

GET /v3/apps/:guid

Query parameters

Name	Type	Description
include	string	Experimental - Optionally include additional related resources in the response. Valid values are space and space.organization.

Permitted roles

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

List apps

Example Request

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

Example Response

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

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

Retrieve all apps the user has access to.

Definition

GET /v3/apps

Query parameters

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

Permitted roles

All Roles

Update an app

Example Request

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

Example Response

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

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

Definition

PATCH /v3/apps/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Delete an app

Example Request

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

Example Response

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

Definition

DELETE /v3/apps/:guid

Permitted roles

Admin
Space Developer

Get current droplet

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

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

Get current droplet association for an app

Example Request

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

Example Response

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

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

This endpoint retrieves the current droplet relationship for an app.

Definition

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

Permitted roles

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

Get environment for an app

Example Request

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

Example Response

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

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

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

Definition

GET /v3/apps/:guid/env

Permitted roles

Admin
Admin Read-Only
Space Developer

Get environment variables for an app

Example Request

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

Example Response

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

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

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

Definition

GET /v3/apps/:guid/environment_variables

Permitted roles

Admin
Admin Read-Only
Space Developer

Set current droplet

Example Request

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

Example Response

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

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

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

Definition

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

Permitted roles

Admin
Space Developer

Get SSH enabled for an app

Example Request

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

Example Response

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

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

Returns if an application’s runtime environment will accept ssh connections. If ssh is disabled, the reason field will describe whether it is disabled globally, at the space level, or at the app level.

Definition

GET /v3/apps/:guid/ssh_enabled

Permitted roles

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

Start an app

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

Admin
Space Developer

Stop an app

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

Admin
Space Developer

Update environment variables for an app

Example Request

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

Example Response

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

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

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

Definition

PATCH /v3/apps/:guid/environment_variables

Permitted roles

Admin
Space Developer

App Features

App features are used to manage whether optional capabilities are enabled for a given application.

The app feature object

Example App Feature object

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

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

Supported app features

Note: SSH must also be enabled globally and on the space.

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

Get an app feature

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

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

List app features

Example Request

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

Example Response

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

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

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

Definition

GET /v3/apps/:guid/features

Permitted roles

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

Update an app feature

Example Request

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

Example Response

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Space Developer

Audit Events

Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions.

For more information and a list of all possible event types, see the Cloud Foundry docs.

The audit event object

Example Audit Event object

{
  "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
  "created_at": "2016-06-08T16:41:23Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "type": "audit.app.update",
  "actor": {
    "guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
    "type": "user",
    "name": "admin"
  },
  "target": {
    "guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
    "type": "app",
    "name": "my-app"
  },
  "data": {
    "request": {
      "recursive": true
    }
  },
  "space": {
    "guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
  },
  "organization": {
    "guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the event.
type	string	The type of the event.
actor.guid	string	Unique identifier for the actor (user or system resource that performed the action).
actor.type	string	The actor type.
actor.name	string	The name of the actor.
target.guid	uuid	Unique identifier for the target (resource that the event acted upon).
target.type	string	The target type.
target.name	string	The name of the target.
data	object	Additional information about event.
space.guid	uuid	Unique identifier for the space where the event occurred. If the event did not occur within a space, the space field will be null.
organization.guid	uuid	Unique identifier for the organization where the event occurred. If the event did not occur within an organization, the organization field will be null.
links	links object	Links to related resources.

Get an audit event

Example Request

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

Example Response

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

{
  "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
  "created_at": "2016-06-08T16:41:23Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "type": "audit.app.update",
  "actor": {
    "guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
    "type": "user",
    "name": "admin"
  },
  "target": {
    "guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
    "type": "app",
    "name": "my-app"
  },
  "data": {
    "request": {
      "recursive": true
    }
  },
  "space": {
    "guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
  },
  "organization": {
    "guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
    }
  }
}

Definition

GET /v3/audit_events/:guid

Permitted roles

Role	Notes
Admin
Admin Read-Only
Global Auditor
Space Auditor	Cannot see events which occurred in spaces that the user does not belong to.
Space Developer	Cannot see events which occurred in spaces that the user does not belong to.
Org Auditor	Cannot see events which occurred in orgs that the user does not belong to.

List audit events

Example Request

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

Example Response

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

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/audit_events?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/audit_events?page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
      "created_at": "2016-06-08T16:41:23Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "type": "audit.app.update",
      "actor": {
        "guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
        "type": "user",
        "name": "admin"
      },
      "target": {
        "guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
        "type": "app",
        "name": "my-app"
      },
      "data": {
        "request": {
          "recursive": true
        }
      },
      "space": {
        "guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
      },
      "organization": {
        "guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
      },
      "links": {
        "self": {
          "href": "https://api.example.org//v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
        }
      }
    }
  ]
}

Retrieve all audit events the user has access to.

Definition

GET /v3/audit_events

Query parameters

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

Permitted roles

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

Builds

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

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

The build object

Example Build object

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

Name	Type	Description
state	string	State of the build. Valid states are STAGING, STAGED, or FAILED.
error	string	A string describing errors during the build process.
lifecycle	lifecycle object	Provides the lifecycle object to use during staging. This will override the build’s application’s default lifecycle for this build.
package	object	The package that is the input to the staging process.
droplet	object	A resulting droplet from the staging process.
guid	uuid	Unique identifier for the build.
created_at	datetime	The time with zone when the build was created.
updated_at	datetime	The time with zone when the build was last updated.
created_by	object	The user that created the build.
relationships.app (experimental)	to-one relationship	The app the build belongs to.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the build.
metadata.annotations (experimental)	annotation object	Annotations applied to the build.

Create a build

Example Request

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

Example Response

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

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

Definition

POST /v3/builds

Required parameters

Name	Type	Description
package	object	App package to stage.

Optional parameters

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

Permitted roles

Admin
Space Developer

Get a build

Example Request

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

Example Response

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

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

Definition

GET /v3/builds/:guid

Permitted roles

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

List builds

Example Request

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

Example Response

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

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

Retrieve all builds the user has access to.

Definition

GET /v3/builds

Query parameters

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

Permitted roles

All Roles

List builds for an app

Example Request

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

Example Response

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

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

Retrieve all builds for the app.

Definition

GET /v3/apps/:guid/builds

Query parameters

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

Permitted roles

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

Update a build

Example Request

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

Example Response

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

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

Definition

PATCH /v3/builds/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the build.
metadata.annotations (experimental)	annotation object	Annotations applied to the build.
state (experimental)	string	Build status (FAILED, STAGED). **
lifecycle.data.image (experimental)	string	Image reference tag where the built complete image was stored. **

Permitted roles

Admin
Space Developer

Special Permitted roles **

Admin
Space Developer
Build State Updater

Buildpacks

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

The buildpack object

Example Buildpack object

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

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

Create a buildpack

Example Request

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

Example Response

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

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

Definition

POST /v3/buildpacks

Required parameters

Name	Type	Description
name	string	Name of the buildpack.

Optional parameters

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

Permitted roles

Admin

Get a buildpack

Example Request

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

Example Response

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

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

Definition

GET /v3/buildpacks/:guid

Permitted roles

All Roles

List buildpacks

Example Request

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

Example Response

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

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

Retrieve all buildpacks the user has access to.

Definition

GET /v3/buildpacks

Query parameters

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

Permitted roles

All Roles

Update a buildpack

Example Request

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

Example Response

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

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

Definition

PATCH /v3/buildpacks/:guid

Optional parameters

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

Permitted roles

Admin

Delete a buildpack

Example Request

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

Example Response

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

Definition

DELETE /v3/buildpacks/:guid

Permitted Roles

Admin

Upload buildpack bits

Example Request

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

Example Response

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

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

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

Definition

POST /v3/buildpacks/:guid/upload

Required parameters

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

Permitted roles

Admin

Deployments

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

They can either:

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

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

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

The deployment object

Example Deployment object

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

Name	Type	Description
state	string	(deprecated) The state of the deployment. Valid values are DEPLOYING, DEPLOYED, CANCELING, or CANCELED. This field will be removed in the future; use the status fields to determine deployment state instead.
status.value	string	The current status of the deployment. Valid values are ACTIVE (meaning in progress) and FINALIZED (meaning finished, either successfully or not).
status.reason	string	The reason for the status of the deployment. Following list represents valid values. 1. If status.value is ACTIVE - DEPLOYING - CANCELING 2. If status.value is FINALIZED - DEPLOYED - CANCELED - SUPERSEDED (another deployment created for app before completion) - DEGENERATE (the deployment was created incorrectly by the system)
status.details	object	The details for the status of the deployment shows a timestamp of the last successful healthcheck.
strategy	string	Strategy used for the deployment. Supported strategies are rolling only.
guid	uuid	Unique identifier for the deployment.
relationships.app	to-one relationship	The app the deployment is updating.
droplet	object	The droplet the deployment is transitioning the app to.
previous_droplet	object	The app’s current droplet before the deployment was created.
new_processes	array	List of processes created as part of the deployment
revision	object	The revision the deployment is transitioning the app to.
metadata.labels (experimental)	label object	Labels applied to the deployment.
metadata.annotations (experimental)	annotation object	Annotations applied to the deployment.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.

Create a deployment

Example Request with Droplet

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

Example Request with Revision

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

Example Response

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


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

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

Definition

POST /v3/deployments

Required parameters

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

Optional parameters

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

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

Permitted roles

Admin
Space Developer

Get a deployment

Example Request

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

Example Response

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


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

Definition

GET /v3/deployments/:guid

Permitted roles

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

List deployments

Example Request

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

Example Response

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

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

Retrieve all deployments the user has access to.

Definition

GET /v3/deployments

Query parameters

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

Permitted roles

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

Update a deployment

Example Request

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

Example Response

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


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

Definition

PATCH /v3/deployments/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Cancel a deployment

Example Request

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

Example Response

HTTP/1.1 200 OK

Definition

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

Permitted roles

Admin
Space Developer

Domains

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

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

The domain object

Example Domain object

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

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

Create a domain

Example Request

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

Example Response

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

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

Definition

POST /v3/domains

Required parameters

Name	Type	Description
name	string	Name of the domain.

Optional parameters

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

Permitted roles

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

Get a domain

Example Request

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

Example Response

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

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

Definition

GET /v3/domains/:guid

Permitted roles

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

List domains

Example Request

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

Example Response

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

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

Retrieve all domains the user has access to.

Definition

GET /v3/domains

Query parameters

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

Permitted roles

All Roles

List domains for an organization

Example Request

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

Example Response

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

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

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

Definition

GET /v3/organizations/:guid/domains

Query parameters

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

Permitted roles

All Roles

Update a domain

Example Request

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

Example Response

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

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

Definition

PATCH /v3/domains/:guid

Optional parameters

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

Permitted roles

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

Delete a domain

Example Request

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

Example Response

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

Definition

DELETE /v3/domains/:guid

Permitted roles

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

Share a domain

Example Request

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

Example Response

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

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

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

Definition

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

Required parameters

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

Permitted roles

Role	Notes
Admin
Org Manager

Unshare a domain

Example Request

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

Example Response

HTTP/1.1 204 No Content

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

Definition

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

Permitted roles

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

Droplets

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

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

The droplet object

Example Droplet object

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

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

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

Buildpack droplet

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

Detected buildpack object

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

Docker droplet

Name	Type	Description
image	string	Docker image name.

Create a droplet

Example Request

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

Example Response

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

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

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

Definition

POST /v3/droplets

Required parameters

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Get a droplet

Example Request

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

Example Response

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

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

Definition

GET /v3/droplets/:guid

Permitted roles

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

List droplets

Example Request

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

Example Response

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

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

Retrieve all droplets the user has access to.

Definition

GET /v3/droplets

Query parameters

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

Permitted roles

All Roles

List droplets for a package

Example Request

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

Example Response

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

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

Retrieve a list of droplets belonging to a package.

Definition

GET /v3/packages/:guid/droplets

Query parameters

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

Permitted roles

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

List droplets for an app

Example Request

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

Example Response

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

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

Retrieve a list of droplets belonging to an app.

Definition

GET /v3/apps/:guid/droplets

Query parameters

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

Permitted roles

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

Update a droplet

Example Request

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

Example Response

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

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

Definition

PATCH /v3/droplets/:guid

Optional parameters

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

Permitted roles

Admin
Org Manager
Space Developer
Space Manager

Delete a droplet

Example Request

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

Example Response

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

Definition

DELETE /v3/droplets/:guid

Permitted Roles

Admin
Space Developer

Copy a droplet

Example Request

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

Example Response

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

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

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

Definition

POST /v3/droplets?source_guid=:guid

Required query parameters

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

Required parameters

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

Permitted roles

Admin
Space Developer

Upload droplet bits

Example Request

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

Example Response

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

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

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

Definition

POST /v3/droplets/:guid/upload

Required parameters

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

Permitted roles

Admin
Space Developer

Environment Variable Groups

There are two types of environment variable groups: running and staging. They are designed to allow platform operators/admins to manage environment variables across all apps in a foundation.

Variables in a running environment variable group will be injected into all running app containers.

Variables in a staging environment variable group will be injected into the staging container for all apps while they are being staged.

The environment variable group object

Example environment variable group object

{
  "updated_at": "2016-05-04T17:00:41Z",
  "name": "running",
  "var": {
    "foo": "bar"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/environment_variable_groups/running"
    }
  }
}

Name	Type	Description
name	string	The name of the group. Can only be running or staging.
updated_at	string	The time of last update.
var	object	Environment variables to inject. Keys and values must be strings.
links	links object	Links to related resources.

Get an environment variable group

Example Request

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

Example Response

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

{
  "updated_at": "2016-05-04T17:00:41Z",
  "name": "running",
  "var": {
    "foo": "bar"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/environment_variable_groups/running"
    }
  }
}

Definition

GET /v3/environment_variable_groups/:name

Permitted roles

All Roles

Update environment variable group

Example Request

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

Example Response

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

{
  "var": {
    "RAILS_ENV": "production",
    "DEBUG": "false"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/environment_variable_groups/[name]"
    }
  }
}

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

Definition

PATCH /v3/environment_variable_groups/:name

Permitted roles

Admin

Feature Flags

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

The feature flag object

Example Feature Flag object

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

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

List of feature flags

Name: app_bits_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: resource_matching Default: true Description: When enabled, any user can create resource matches. When disabled, the resource match endpoint always returns an empty array of matches.
Name: route_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

Info

Info endpoints expose Cloud Controller configuration information.

Get platform info

Example Request

curl "https://api.example.org/v3/info" \
  -X GET

Example Response with configured values

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

{
  "build": "afa73e3fe",
  "cli_version": {
    "minimum": "6.22.0",
    "recommended": "latest"
  },
  "custom": {
    "arbitrary": "stuff"
  },
  "description": "Put your apps here!",
  "name": "Cloud Foundry",
  "version": 123,
  "links": {
    "self": { "href": "http://api.example.com/v3/info" } ,
    "support": { "href": "http://support.example.com" }
  }
}

Example Response with unconfigured values

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

{
  "build": "",
  "cli_version": {
    "minimum": "",
    "recommended": ""
  },
  "custom": {},
  "description": "",
  "name": "",
  "version": 0,
  "links": {
    "self": { "href": "http://api.example.com/v3/info" } ,
    "support": { "href": "" }
  }
}

Definition

GET /v3/info

Authentication

No authentication required.

Isolation Segments

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

The isolation segment object

Example Isolation Segment object

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

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

Create an isolation segment

Example Request

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

Example Response

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

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

Definition

POST /v3/isolation_segments

Required parameters

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

Permitted roles

Admin

Get an isolation segment

Example Request

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

Example Response

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

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

Definition

GET /v3/isolation_segments/:guid

Permitted roles

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

List isolation segments

Example Request

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

Example Response

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

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

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

Definition

GET /v3/isolation_segments

Query parameters

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

Permitted roles

All Roles

List organizations relationship

Example Request

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

Example Response

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

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

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

Definition

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

Permitted roles

All Roles

List spaces relationship

Example Request

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

Example Response

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

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

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

Definition

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

Permitted roles

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

Update an isolation segment

Example Request

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

Example Response

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

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

Definition

PATCH /v3/isolation_segments/:guid

Optional parameters

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

Permitted roles

Admin

Delete an isolation segment

Example Request

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

Example Response

HTTP/1.1 204 No Content

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

Definition

DELETE /v3/isolation_segments/:guid

Permitted roles

Admin

Entitle organizations for an isolation segment

Example Request

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

Example Response

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

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

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

Definition

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

Required parameters

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

Permitted roles

Admin

Revoke entitlement to isolation segment for an organization

Example Request

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

Example Response

HTTP/1.1 204 No Content

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

Definition

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

Permitted roles

Admin

Jobs

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

The job object

Example Job object

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

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

Get a job

Example Request

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

Completed Job Example Response

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

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

Failed Job Example Response

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

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

Definition

GET /v3/jobs/:guid

Permitted roles

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

Organizations

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

The organization object

Example Organization object

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

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

Create an organization

Example Request

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

Example Response

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

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

Definition

POST /v3/organizations

Required parameters

Name	Type	Description
name	string	Organization name

Optional parameters

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

Permitted roles

Admin

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

Get an organization

Example Request

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

Example Response

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

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

This endpoint retrieves the specified organization object.

Definition

GET /v3/organizations/:guid

Permitted roles

All Roles

List organizations

Example Request

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

Example Response

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

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

Retrieve all organizations the user has access to.

Definition

GET /v3/organizations

Query parameters

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

Permitted roles

All Roles

List organizations for isolation segment

Example Request

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

Example Response

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

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

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

Definition

GET /v3/isolation_segments/:guid/organizations

Query parameters

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

Permitted roles

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

Update an organization

Example Request

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

Example Response

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

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

Definition

PATCH /v3/organizations/:guid

Optional parameters

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

Permitted roles

Admin
Org Manager

Delete an organization

When an organization is deleted, user roles associated with the organization will also be deleted.

Example Request

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

Example Response

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

Definition

DELETE /v3/organizations/:guid

Permitted roles

Role	Notes
Admin

Assign default isolation segment

Example Request

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

Example Response

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

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Org Manager

Get default isolation segment

Example Request

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

Example Response

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

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

Retrieve the default isolation segment for a given organization.

Definition

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

Permitted roles

All Roles

Get default domain

Example Request

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

Example Response

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

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

Retrieve the default domain for a given organization.

Definition

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

Permitted roles

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

Get usage summary

Example Request

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

Example Response

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

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

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

Definition

GET /v3/organizations/:guid/usage_summary

Permitted roles

All Roles

Organization Quotas

Organization quotas are named sets of memory, service, and instance usage quotas. For example, one organization quota might allow up to 10 services, 10 routes, and 2 GB of RAM, while another might offer 100 services, 100 routes, and 10 GB of RAM.

An organization has exactly one organization quota. If not specifically assigned a quota, it will have the default quota.

For more information, see the Cloud Foundry docs.

The organization quota object

Example Organization Quota object

  {
    "guid": "quota-guid",
    "created_at": "2016-05-04T17:00:41Z",
    "updated_at": "2016-05-04T17:00:41Z",
    "name": "don-quixote",
    "apps": {
      "total_memory_in_mb": 5120,
      "per_process_memory_in_mb": 1024,
      "total_instances": 10,
      "per_app_tasks": 5
    },
    "services": {
      "paid_services_allowed": true,
      "total_service_instances": 10,
      "total_service_keys": 20
    },
    "routes": {
      "total_routes": 8,
      "total_reserved_ports": 4
    },
    "domains": {
      "total_domains": 7
    },
    "relationships": {
      "organizations": {
        "data": [
          { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
        ]
      }
    },
    "links": {
      "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
    }
  }

Name	Type	Description
guid	uuid	Unique identifier for the organization quota.
created_at	datetime	The time with zone when the organization quota was created.
updated_at	datetime	The time with zone when the organization quota was last updated.
name	string	Name of the quota.
apps	object	Quotas that affect applications and application sub-resources.
apps.per_process_memory_in_mb	integer or null	Maximum memory for a single process or task.
apps.total_memory_in_mb	integer or null	Total memory allowed for all the started processes and running tasks in an organization.
apps.total_instances	integer or null	Total instances of all the started processes allowed in an organization.
apps.per_app_tasks	integer or null	Maximum number of running tasks in a single application.
services	object	Quotas that affect services.
services.paid_services_allowed	boolean	Specifies whether instances of paid service plans can be created.
services.total_service_instances	integer or null	Total number of service instances allowed in an organization.
services.total_service_keys	integer or null	Total number of service keys allowed in an organization.
routes	object	Quotas that affect routes.
routes.total_routes	integer or null	Total number of routes allowed in an organization.
routes.total_reserved_ports	integer or null	Total number of ports that are reservable by routes in an organization.
domains	object	Quotas that affect domains.
domains.total_domains	integer or null	Total number of domains that can be scoped to an organization.
relationships.organizations	to-many relationship	A relationship to the organizations where the quota is applied.
links	links object	Links to related resources.

Create an organization quota

Example Request

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

Example Response

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

  {
    "guid": "quota-guid",
    "created_at": "2016-05-04T17:00:41Z",
    "updated_at": "2016-05-04T17:00:41Z",
    "name": "don-quixote",
    "apps": {
      "total_memory_in_mb": 5120,
      "per_process_memory_in_mb": 1024,
      "total_instances": 10,
      "per_app_tasks": 5
    },
    "services": {
      "paid_services_allowed": true,
      "total_service_instances": 10,
      "total_service_keys": 20
    },
    "routes": {
      "total_routes": 8,
      "total_reserved_ports": 4
    },
    "domains": {
      "total_domains": 7
    },
    "relationships": {
      "organizations": {
        "data": [
          { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
        ]
      }
    },
    "links": {
      "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
    }
  }

This endpoint creates a new organization quota, but does not assign it to a specific organization unless an organization GUID is provided in the relationships.organizations parameter.

To create an organization quota you must be an admin.

Definition

POST /v3/organization_quotas

Required parameters

Name	Type	Description
name	string	Name of the quota.

Optional parameters

Name	Type	Description	Default
apps	object	Quotas that affect applications and application sub-resources.
apps.per_process_memory_in_mb	integer or null	Maximum memory for a single process or task.	null (infinite)
apps.total_memory_in_mb	integer or null	Total memory allowed for all the started processes and running tasks in an organization.	null (infinite)
apps.total_instances	integer or null	Total instances of all the started processes allowed in an organization.	null (infinite)
apps.per_app_tasks	integer or null	Maximum number of running tasks in a single application.	null (infinite)
services	object	Quotas that affect services.
services.paid_services_allowed	boolean	Specifies whether instances of paid service plans can be created.	true
services.total_service_instances	integer or null	Total number of service instances allowed in an organization.	null (infinite)
services.total_service_keys	integer or null	Total number of service keys allowed in an organization.	null (infinite)
routes	object	Quotas that affect routes.
routes.total_routes	integer or null	Total number of routes allowed in an organization.	null (infinite)
routes.total_reserved_ports	integer or null	Total number of ports that are reservable by routes in an organization.	null (infinite)
domains	object	Quotas that affect domains.
domains.total_domains	integer or null	Total number of domains that can be scoped to an organization.	null (infinite)
relationships.organizations	to-many relationship	A relationship to the organizations where the quota is applied.	[]

Permitted roles

Role	Notes
Admin

Get an organization quota

Example Request

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

Example Response

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

  {
    "guid": "quota-guid",
    "created_at": "2016-05-04T17:00:41Z",
    "updated_at": "2016-05-04T17:00:41Z",
    "name": "don-quixote",
    "apps": {
      "total_memory_in_mb": 5120,
      "per_process_memory_in_mb": 1024,
      "total_instances": 10,
      "per_app_tasks": 5
    },
    "services": {
      "paid_services_allowed": true,
      "total_service_instances": 10,
      "total_service_keys": 20
    },
    "routes": {
      "total_routes": 8,
      "total_reserved_ports": 4
    },
    "domains": {
      "total_domains": 7
    },
    "relationships": {
      "organizations": {
        "data": [
          { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
        ]
      }
    },
    "links": {
      "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
    }
  }

This endpoint gets an individual organization quota resource.

Definition

GET /v3/organization_quotas/:guid

Permitted roles

Role	Notes
Admin
Admin Read-Only
Global Auditor
Org Manager	Response will only include guids of managed organizations.
Org Auditor	Response will only include guids of audited organizations.
Org Billing Manager	Response will only include guids of billing-managed organizations.
Space Auditor	Response will only include guids of parent organizations.
Space Developer	Response will only include guids of parent organizations.
Space Manager	Response will only include guids of parent organizations.

List organization quotas

Example Request

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

Example Response

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

  {
    "pagination": {
      "total_results": 2,
      "total_pages": 1,
      "first": {
        "href": "https://api.example.org/v3/organization_quotas?page=1&per_page=50"
      },
      "last": {
        "href": "https://api.example.org/v3/organization_quotas?page=1&per_page=50"
      },
      "next": null,
      "previous": null
    },
    "resources": [
      {
        "guid": "quota-1-guid",
        "created_at": "2016-05-04T17:00:41Z",
        "updated_at": "2016-05-04T17:00:41Z",
        "name": "don-quixote",
        "apps": {
          "total_memory_in_mb": 5120,
          "per_process_memory_in_mb": 1024,
          "total_instances": 10,
          "per_app_tasks": 5
        },
        "services": {
          "paid_services_allowed": true,
          "total_service_instances": 10,
          "total_service_keys": 20
        },
        "routes": {
          "total_routes": 8,
          "total_reserved_ports": 4
        },
        "domains": {
          "total_domains": 7
        },
        "relationships": {
          "organizations": {
            "data": [
              { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
            ]
          }
        },
        "links": {
          "self": { "href": "https://api.example.org/v3/organization_quotas/quota-1-guid" }
        }
      },
      {
        "guid": "quota-2-guid",
        "created_at": "2017-05-04T17:00:41Z",
        "updated_at": "2017-05-04T17:00:41Z",
        "name": "sancho-panza",
        "apps": {
          "total_memory_in_mb": 2048,
          "per_process_memory_in_mb": 1024,
          "total_instances": 5,
          "per_app_tasks": 2
        },
        "services": {
          "paid_services_allowed": true,
          "total_service_instances": 10,
          "total_service_keys": 20
        },
        "routes": {
          "total_routes": 8,
          "total_reserved_ports": 4
        },
        "domains": {
          "total_domains": 7
        },
        "relationships": {
          "organizations": {
            "data": []
          }
        },
        "links": {
          "self": { "href": "https://api.example.org/v3/organization_quotas/quota-2-guid" }
        }
      }
    ]
  }

This endpoint lists all organization quota resources.

Definition

GET /v3/organization_quotas

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

Permitted roles

Role	Notes
Admin
Admin Read-Only
Global Auditor
Org Manager	Response will only include guids of managed organizations.
Org Auditor	Response will only include guids of audited organizations.
Org Billing Manager	Response will only include guids of billing-managed organizations.
Space Auditor	Response will only include guids of parent organizations.
Space Developer	Response will only include guids of parent organizations.
Space Manager	Response will only include guids of parent organizations.

Apply an organization quota to an organization

Example Request

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

Example Response

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

  {
    "data": [
      { "guid": "org-guid1" },
      { "guid": "org-guid2" },
      { "guid": "previous-org-guid" }
    ],
    "links": {
      "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid/relationships/organizations" }
    }
  }

This endpoint applies an organization quota to one or more organizations.

Only admin users can apply an organization quota to an organization.

Definition

POST /v3/organization_quotas/:quota_guid/relationships/organizations

Required parameters

Name	Type	Description
data	to-many relationship	Organization guids that the quota will apply to.

Permitted roles

Role	Notes
Admin

Delete an organization quota

Organization quotas cannot be deleted when applied to any organizations.

Example Request

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

Example Response

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

Definition

DELETE /v3/organization_quotas/:guid

Permitted roles

Role	Notes
Admin

Update an organization quota

Example Request

curl "https://api.example.org/v3/organization_quotas/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "don-quixote",
    "apps": {
      "total_memory_in_mb": 5120,
      "per_process_memory_in_mb": 1024,
      "total_instances": 10,
      "per_app_tasks": 5
    },
    "services": {
      "paid_services_allowed": true,
      "total_service_instances": 10,
      "total_service_keys": 20,
    },
    "routes": {
      "total_routes": 8,
      "total_reserved_ports": 4
    },
    "domains": {
      "total_private_domains": 7
    }
  }'

Example Response

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

  {
    "guid": "quota-guid",
    "created_at": "2016-05-04T17:00:41Z",
    "updated_at": "2016-05-04T17:00:41Z",
    "name": "don-quixote",
    "apps": {
      "total_memory_in_mb": 5120,
      "per_process_memory_in_mb": 1024,
      "total_instances": 10,
      "per_app_tasks": 5
    },
    "services": {
      "paid_services_allowed": true,
      "total_service_instances": 10,
      "total_service_keys": 20
    },
    "routes": {
      "total_routes": 8,
      "total_reserved_ports": 4
    },
    "domains": {
      "total_domains": 7
    },
    "relationships": {
      "organizations": {
        "data": [
          { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
        ]
      }
    },
    "links": {
      "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
    }
  }

This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values.

Definition

PATCH /v3/organization_quotas/:guid

Optional parameters

Name	Type	Description
name	string	Name of the quota.
apps	object	Quotas that affect applications and application sub-resources.
apps.per_process_memory_in_mb	integer or null	Maximum memory for a single process or task.
apps.total_memory_in_mb	integer or null	Total memory of all the started processes and running tasks in an organization.
apps.total_instances	integer or null	Total instances of all the started processes in an organization.
apps.per_app_tasks	integer or null	Maximum number of running tasks in a single application.
services	object	Quotas that affect services.
services.paid_services_allowed	boolean	If instances of paid service plans can be created.
services.total_service_instances	integer or null	Total number of service instances in an organization.
services.total_service_keys	integer or null	Total number of service keys in an organization.
routes	object	Quotas that affect routes.
routes.total_routes	integer or null	Total number of routes that an organization can have.
routes.total_reserved_ports	integer or null	Total number of ports that all routes in an organization can reserve.
domains	object	Quotas that affect domains.
domains.total_domains	integer or null	Total number of domains that can be scoped to an organization.

Permitted roles

Role	Notes
Admin

Packages

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

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

The package object

Example Package object

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

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

Bits package

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

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

Docker package

A Docker package references a Docker image from a registry.

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

Create a package

Example Request (buildpack app)

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

Example Response

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

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

Example Request (Docker app)

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

Example Response

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

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

Definition

POST /v3/packages

Required parameters

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

Optional parameters

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

Conditional Parameters

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

Permitted roles

Admin
Space Developer

Get a package

Example Request

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

Example Response

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

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

Definition

GET /v3/packages/:guid

Permitted roles

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

List packages

Example Request

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

Example Response

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

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

Retrieve all packages the user has access to.

Definition

GET /v3/packages

Query parameters

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

Permitted roles

All Roles

List packages for an app

Example Request

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

Example Response

HTTP/1.1 200 OK

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

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

Definition

GET /v3/apps/:guid/packages

Query parameters

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

Permitted roles

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

Update a package

Example Request

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

Example Response

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

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

Definition

PATCH /v3/packages/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Delete a package

Example Request

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

Example Response

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

Definition

DELETE /v3/packages/:guid

Permitted Roles

Admin
Space Developer

Copy a package

Example Request

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

Example Response

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

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

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

Definition

POST /v3/packages?source_guid=:guid

Required query parameters

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

Required parameters

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

Permitted roles

Admin
Space Developer

Download package bits

Example Request

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

Example Response

HTTP/1.1 302 Found

You are being redirected.

This endpoint downloads the bits of an existing package.

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

Definition

GET /v3/packages/:guid/download

Permitted roles

Admin
Space Developer

Stage a package

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

Upload package bits

Example Request

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

Example Response

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

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

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

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

Definition

POST /v3/packages/:guid/upload

Optional parameters

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

Permitted roles

Admin
Space Developer

Processes

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

Web process type

• By default, a newly created app will come with one instance of the 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": {
    "app": {
      "data": {
        "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
      }
    },
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
      "method": "POST"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

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

The health check object

Example health check object

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

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

The process stats object

Example process stats object

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

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

Get a process

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

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

Get stats for a process

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

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

List processes

Example Request

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

Example Response

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

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

Retrieve all processes the user has access to.

Definition

GET /v3/processes

Query parameters

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

Permitted roles

All Roles

List processes for app

Example Request

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

Example Response

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

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

Retrieves all processes belonging to an app.

Definition

GET /v3/apps/:guid/processes

Query parameters

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

Permitted roles

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

Update a process

Example Request

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

Example Response

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

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

Definition

PATCH /v3/processes/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Scale a process

Example Request

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

Example Response

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

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

Definition

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Terminate a process instance

Example Request

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

Example Response

HTTP/1.1 204 No Content

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

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

Definition

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

Permitted Roles

Admin
Space Developer

Resource Matches

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

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

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

If the resource_matching feature flag is disabled, resource matching will always return an empty array.

The resource match object

Example Resource Match object

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

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

Create a resource match

Example Request

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

Example Response

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

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

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

Definition

POST /v3/resource_matches

Required parameters

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

Permitted roles

All Roles

Roles

Roles control access to resources in organizations and spaces. Roles are assigned to users.

For example, a user with the space_developer role is able to push applications to their space. A space_manager user can also add roles to users within that space (e.g. making a user a space_auditor). An organization_manager has wide-reaching privileges, able to create & delete spaces, and assign & unassign roles to users.

The role object

Example Role object

{
   "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
   "created_at": "2019-10-10T17:19:12Z",
   "updated_at": "2019-10-10T17:19:12Z",
   "type": "organization_auditor",
   "relationships": {
      "user": {
         "data": {
            "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
         }
      },
      "organization": {
         "data": {
            "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
         }
      },
      "space": {
         "data": null
      }
   },
   "links": {
      "self": {
         "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
      },
      "user": {
         "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
      },
      "organization": {
         "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
      }
   }
}

Name	Type	Description
guid	uuid	Unique identifier for the role.
created_at	datetime	The time with zone when the role was created.
updated_at	datetime	The time with zone when the role was last updated.
type	string	Role type. See Valid role types.
relationships.user	to-one relationship	A relationship to the user. This is the user that has the role.
relationships.space	to-one relationship	A relationship to the space the role controls access to. When this is an organization role, space.data will be null.
relationships.organization	to-one relationship	A relationship to the organization the role controls access to. When this is a space role, organization.data will be null.
links	links object	Links to related resources.

Valid role types

• organization_user
• organization_auditor
• organization_manager
• organization_billing_manager
• space_auditor
• space_developer
• space_manager

Create a role

Example Request (by user guid)

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

Example Response

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

{
   "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
   "created_at": "2019-10-10T17:19:12Z",
   "updated_at": "2019-10-10T17:19:12Z",
   "type": "organization_auditor",
   "relationships": {
      "user": {
         "data": {
            "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
         }
      },
      "organization": {
         "data": {
            "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
         }
      },
      "space": {
         "data": null
      }
   },
   "links": {
      "self": {
         "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
      },
      "user": {
         "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
      },
      "organization": {
         "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
      }
   }
}

Example Request (by username and origin)

curl "https://api.example.org/v3/roles" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
      "type": "organization_auditor",
      "relationships": {
        "user": {
          "data": {
            "username": "user-name",
            "origin": "ldap"
          }
        },
        "organization": {
          "data": {
            "guid": "org-guid"
          }
        }
      }
    }'

Example Response

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

{
   "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
   "created_at": "2019-10-10T17:19:12Z",
   "updated_at": "2019-10-10T17:19:12Z",
   "type": "organization_auditor",
   "relationships": {
      "user": {
         "data": {
            "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
         }
      },
      "organization": {
         "data": {
            "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
         }
      },
      "space": {
         "data": null
      }
   },
   "links": {
      "self": {
         "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
      },
      "user": {
         "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
      },
      "organization": {
         "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
      }
   }
}

This endpoint creates a new role for a user in an organization or space.

To create an organization role you must be an admin or organization manager in the organization associated with the role.

To create a space role you must be an admin, an organization manager in the parent organization of the space associated with the role, or a space manager in the space associated with the role.

For a user to be assigned a space role, the user must already have an organization role in the parent organization.

If the associated user is valid but does not exist in Cloud Controller’s database, a user resource will be created automatically.

Definition

POST /v3/roles

Required parameters

Name	Type	Description
type	string	Role to create. See valid role types.
relationships.user	to-one relationship	A relationship to a user. The user can be defined by either a guid or, if the set_roles_by_username feature_flag is enabled, a username (with the option of including an origin to disambiguate it).
relationships.organization	to-one relationship	A relationship to an organization. Required only when creating an organization role.
relationships.space	to-one relationship	A relationship to a space. Required only when creating a space role.

Permitted roles

Role	Notes
Admin
Org Manager	Can create roles in managed organizations and spaces within those organizations. Can also create roles for users outside of managed organizations when set_roles_by_username feature_flag is enabled. This requires identifying users by username and origin.
Space Manager	Can create roles in managed spaces for users in their org.

Get a role

Example Request

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

Example Response

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

{
   "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
   "created_at": "2019-10-10T17:19:12Z",
   "updated_at": "2019-10-10T17:19:12Z",
   "type": "organization_auditor",
   "relationships": {
      "user": {
         "data": {
            "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
         }
      },
      "organization": {
         "data": {
            "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
         }
      },
      "space": {
         "data": null
      }
   },
   "links": {
      "self": {
         "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
      },
      "user": {
         "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
      },
      "organization": {
         "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
      }
   }
}

This endpoint gets an individual role resource.

Definition

GET /v3/roles/:guid

Query parameters

Name	Type	Description
include	list of strings	Experimental - Optionally include a list of unique related resources in the response. Valid values are user, space, and organization.

Permitted roles

Role	Notes
Admin
Admin Read-Only
Global Auditor
Org Manager	Can see roles in managed organizations or spaces in those organizations.
Org Auditor	Can only see organization roles in audited organizations.
Org Billing Manager	Can only see organization roles in billing-managed organizations.
Space Auditor	Can see roles in audited spaces or parent organizations.
Space Developer	Can see roles in developed spaces or parent organizations.
Space Manager	Can see roles in managed spaces or parent organizations.

List roles

Example Request

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

Example Response

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

{
   "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
         "href": "https://api.example.org/v3/roles?page=1&per_page=2"
      },
      "last": {
         "href": "https://api.example.org/v3/roles?page=2&per_page=2"
      },
      "next": {
         "href": "https://api.example.org/v3/roles?page=2&per_page=2"
      },
      "previous": null
   },
   "resources": [
      {
         "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
         "created_at": "2019-10-10T17:19:12Z",
         "updated_at": "2019-10-10T17:19:12Z",
         "type": "organization_auditor",
         "relationships": {
            "user": {
               "data": {
                  "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
               }
            },
            "organization": {
               "data": {
                  "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
               }
            },
            "space": {
               "data": null
            }
         },
         "links": {
            "self": {
               "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
            },
            "user": {
               "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
            },
            "organization": {
               "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
            }
         }
      },
      {
         "guid": "12347c70-d1bd-4976-a2ab-a85f5e882418",
         "created_at": "2047-11-10T17:19:12Z",
         "updated_at": "2047-11-10T17:19:12Z",
         "type": "space_auditor",
         "relationships": {
            "user": {
               "data": {
                  "guid": "47eadb5f-fc13-414f-84ba-47a35e239cc8"
               }
            },
            "organization": {
               "data": null
            },
            "space": {
               "data": {
                  "guid": "47c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
               }
            }
         },
         "links": {
            "self": {
               "href": "https://api.example.org/v3/roles/12347c70-d1bd-4976-a2ab-a85f5e882418"
            },
            "user": {
               "href": "https://api.example.org/v3/users/47eadb5f-fc13-414f-84ba-77a35e239cc8"
            },
            "space": {
               "href": "https://api.example.org/v3/spaces/47c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
            }
         }
      }
   ]
}

This endpoint lists roles that the user has access to.

Definition

GET /v3/roles

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of role guids to filter by.
types	list of strings	Comma-delimited list of role types to filter by.
space_guids	list of strings	Comma-delimited list of space guids to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids to filter by.
user_guids	list of strings	Comma-delimited list of user guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.
include	list of strings	Experimental - Optionally include a list of unique related resources in the response. Valid values are user, space, and organization.

Permitted roles

All Roles

Delete a role

This endpoint deletes an individual role.

Example Request

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

Example Response

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

Definition

DELETE /v3/roles/:guid

Permitted roles

Role	Notes
Admin
Org Manager	Can delete roles in managed organizations or spaces in those organizations.
Space Manager	Can delete roles in managed spaces

Routes

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

The route object

Example Route object

{
  "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
  "created_at": "2019-05-10T17:17:48Z",
  "updated_at": "2019-05-10T17:17:48Z",
  "host": "a-hostname",
  "path": "/some_path",
  "url": "a-hostname.a-domain.com/some_path",
  "destinations": [
    {
      "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
      "app": {
        "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    }
 ],
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
      }
    },
    "domain": {
      "data": {
        "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
    },
    "domain": {
      "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
    },
    "destinations": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
    }
  }
}

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

The destination object

Example Destination object

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

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

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

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

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

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

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

Create a route

Example Request

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

Example Response

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

{
  "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
  "created_at": "2019-05-10T17:17:48Z",
  "updated_at": "2019-05-10T17:17:48Z",
  "host": "a-hostname",
  "path": "/some_path",
  "url": "a-hostname.a-domain.com/some_path",
  "destinations": [
    {
      "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
      "app": {
        "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    }
 ],
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
      }
    },
    "domain": {
      "data": {
        "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
    },
    "domain": {
      "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
    },
    "destinations": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
    }
  }
}

Definition

POST /v3/routes

Required parameters

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

Optional parameters

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

Permitted roles

Role	Notes
Admin
Space Developer

Get a route

Example Request

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

Example Response

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

{
  "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
  "created_at": "2019-05-10T17:17:48Z",
  "updated_at": "2019-05-10T17:17:48Z",
  "host": "a-hostname",
  "path": "/some_path",
  "url": "a-hostname.a-domain.com/some_path",
  "destinations": [
    {
      "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
      "app": {
        "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    }
 ],
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
      }
    },
    "domain": {
      "data": {
        "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
    },
    "domain": {
      "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
    },
    "destinations": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
    }
  }
}

Definition

GET /v3/routes/:guid

Query parameters

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

Permitted roles

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

List routes

Example Request

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

Example Response

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/routes?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/routes?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/routes?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
      "created_at": "2019-05-10T17:17:48Z",
      "updated_at": "2019-05-10T17:17:48Z",
      "host": "a-hostname",
      "path": "/some_path",
      "url": "a-hostname.a-domain.com/some_path",
      "destinations": [
        {
          "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
          "app": {
            "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
            "process": {
              "type": "web"
            }
          },
          "weight": null,
          "port": 8080
        },
        {
          "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
          "app": {
            "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
            "process": {
              "type": "web"
            }
          },
          "weight": null,
          "port": 8080
        }
      ],
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "relationships": {
        "space": {
          "data": {
            "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
          }
        },
        "domain": {
          "data": {
            "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
        },
        "domain": {
          "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
        },
        "destinations": {
          "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
        }
      }
    }
  ]
}

Retrieve all routes the user has access to.

Definition

GET /v3/routes

Query parameters

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

Permitted roles

All Roles

List routes for an app

Example Request

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

Example Response

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
      "created_at": "2019-05-10T17:17:48Z",
      "updated_at": "2019-05-10T17:17:48Z",
      "host": "a-hostname",
      "path": "/some_path",
      "url": "a-hostname.a-domain.com/some_path",
      "destinations": [
        {
          "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
          "app": {
            "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
            "process": {
              "type": "web"
            }
          },
          "weight": null,
          "port": 8080
        },
        {
          "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
          "app": {
            "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
            "process": {
              "type": "web"
            }
          },
          "weight": null,
          "port": 8080
        }
      ],
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "relationships": {
        "space": {
          "data": {
            "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
          }
        },
        "domain": {
          "data": {
            "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
        },
        "domain": {
          "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
        },
        "destinations": {
          "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
        }
      }
    }
  ]
}

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

Definition

GET /v3/apps/:guid/routes

Query parameters

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

Permitted roles

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

Update a route

Example Request

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

Example Response

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

{
  "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
  "created_at": "2019-05-10T17:17:48Z",
  "updated_at": "2019-05-10T17:17:48Z",
  "host": "a-hostname",
  "path": "/some_path",
  "url": "a-hostname.a-domain.com/some_path",
  "destinations": [
    {
      "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
      "app": {
        "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    }
 ],
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
      }
    },
    "domain": {
      "data": {
        "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
    },
    "domain": {
      "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
    },
    "destinations": {
      "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
    }
  }
}

Definition

PATCH /v3/routes/:guid

Optional parameters

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

Permitted roles

Role	Notes
Admin
Space Developer

Delete a route

Example Request

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

Example Response

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

Definition

DELETE /v3/routes/:guid

Permitted roles

Role	Notes
Admin
Space Developer

Check reserved routes for a domain

Example Request

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

Example Response

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

  { "matching_route": true }

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

Definition

GET /v3/domains/:guid/route_reservations

Query parameters

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

Permitted roles

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

List destinations for a route

Example Request

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

Example Response

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

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

Retrieve all destinations associated with a route.

Definition

GET /v3/routes/:guid/destinations

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of destination guids to filter by.
app_guids	list of strings	Comma-delimited list of app guids to filter by.

Permitted roles

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

Insert destinations for a route

Example Request

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

Example Response

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

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

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

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

Definition

POST /v3/routes/:guid/destinations

Required parameters

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

Permitted roles

Role
Admin
Space Developer

Replace all destinations for a route

Example Request

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

Example Response

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

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

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

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

Definition

PATCH /v3/routes/:guid/destinations

Required parameters

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

Permitted roles

Role
Admin
Space Developer

Remove destination for a route

Example Request

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

Example Response

HTTP/1.1 204 No Content

Remove a destination from a route.

Definition

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

Permitted roles

Role	Notes
Admin
Space Developer

Delete unmapped routes for a space

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

Role	Notes
Admin
Space Developer

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

Service Instances

An instantiation of a service offering.

The service instance object

Example Service Instance object

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

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

List service instances

Example Request

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

Example Response

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

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

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

This includes access granted by service instance sharing.

Definition

GET /v3/service_instances

Query parameters

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

Permitted roles

All Roles

List shared spaces relationship

Example Request

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

Example Response

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

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

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

Definition

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

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

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

Update a service instance

Example Request

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

Example Response

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

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

Definition

PATCH /v3/service_instances/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Share a service instance to other spaces

Example Request

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

Example Response

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

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Space Developer

Unshare a service instance from another space

Example Request

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

Example Response

HTTP/1.1 204 No Content

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

Definition

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

Permitted roles

Admin
Space Developer

Spaces

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

The space object

Example Space object

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

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

Create a space

Example Request

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

Example Response

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

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

Definition

POST /v3/spaces

Required parameters

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

Optional parameters

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

Permitted roles

Admin
Org Manager

Get a space

Example Request

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

Example Response

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

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

This endpoint retrieves the specified space object.

Definition

GET /v3/spaces/:guid

Query parameters

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

Permitted roles

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

List spaces

Example Request

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

Example Response

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

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

Retrieve all spaces the user has access to.

Definition

GET /v3/spaces

Query parameters

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

Permitted roles

All Roles

Update a space

Example Request

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

Example Response

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

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

Definition

PATCH /v3/spaces/:guid

Optional parameters

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

Permitted roles

Admin
Org Manager
Space Manager

Delete a space

When a space is deleted, the user roles associated with the space will be deleted.

Example Request

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

Example Response

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

Definition

DELETE /v3/spaces/:guid

Permitted roles

Role	Notes
Admin
Org Manager

Get assigned isolation segment

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

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

Manage isolation segment

Example Request

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

Example Response

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

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Org Manager

Space Features

Space features are used to manage whether optional capabilities are enabled for a given space.

Currently, the only space feature is SSH (ssh), which controls whether applications in the space may be accessed via SSH.

Note: SSH must also be enabled globally and on the app.

The space feature object

Example Space Feature object

{
  "name": "ssh",
  "description": "Enable SSHing into apps in the space.",
  "enabled": true
}

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

Get a space feature

Example Request

curl "https://api.example.org/v3/spaces/[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 apps in the space.",
  "enabled": true
}

Definition

GET /v3/spaces/:guid/features/:name

Permitted roles

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

List space features

This endpoint retrieves the list of features for the specified space. Currently, the only feature on spaces is the SSH feature.

Example Request

curl "https://api.example.org/v3/spaces/[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 apps in the space.",
      "enabled": false
    }
  ]
}

Definition

GET /v3/spaces/:guid/features

Permitted roles

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

Update space features

Example Request

curl "https://api.example.org/v3/spaces/[guid]/features/[name]" \
  -X PATCH \
  -H "Authorization: bearer [token]"
  -d '{ "enabled": true }'

Example Response

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

{
  "name": "ssh",
  "description": "Enable SSHing into apps in the space.",
  "enabled": true
}

Definition

PATCH /v3/spaces/:guid/features/:name

Permitted roles

Admin
Org Manager
Space Manager

Space Quotas

Space quotas are named sets of quotas. Space quota names are unique within an organization. For example, an organization may only have one space quota named “production”, but two organizations may have two distinct space quotas, both named “production”.

Only one space quota may be applied to a given space at any given time.

Space quotas cannot be used to bypass organization quotas. When the organization’s quota and the space’s quota specify a different values for a given resource, the more restrictive of the two is used. In the event of permissions, the more restrictive permission is used.

The space quota object

Example Space Quota object

{
  "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:41Z",
  "name": "don-quixote",
  "apps": {
    "total_memory_in_mb": 5120,
    "per_process_memory_in_mb": 1024,
    "total_instances": 10,
    "per_app_tasks": null
  },
  "services": {
    "paid_services_allowed": true,
    "total_service_instances": 10,
    "total_service_keys": 20
  },
  "routes": {
    "total_routes": 8,
    "total_reserved_ports": 20
  },
  "relationships": {
    "organization": {
      "data": {
        "guid": "9b370018-c38e-44c9-86d6-155c76801104"
      }
    },
    "spaces": {
      "data": [
        {
          "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
        }
      ]
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the space quota.
created_at	datetime	The time with zone when the space quota was created.
updated_at	datetime	The time with zone when the space quota was last updated.
name	string	Name of the quota.
apps	object	Quotas that affect applications and application sub-resources.
apps.per_process_memory_in_mb	integer or null	Maximum memory for a single process or task.
apps.total_memory_in_mb	integer or null	Total memory allowed for all the started processes and running tasks in a space.
apps.total_instances	integer or null	Total instances of all the started processes allowed in a space.
apps.per_app_tasks	integer or null	Maximum number of running tasks in a single application.
services	object	Quotas that affect services.
services.paid_services_allowed	boolean	Specifies whether instances of paid service plans can be created.
services.total_service_instances	integer or null	Total number of service instances allowed in a space.
services.total_service_keys	integer or null	Total number of service keys allowed in a space.
routes	object	Quotas that affect routes.
routes.total_routes	integer or null	Total number of routes allowed in a space.
routes.total_reserved_ports	integer or null	Total number of ports that are reservable by routes in a space.
relationships.organization	to-one relationship	A relationship to the organization where the quota belongs.
relationships.spaces	to-many relationship	A relationship to the spaces where the quota is applied.
links	links object	Links to related resources.

Create a space quota

Example Request

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

Example Response

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

{
  "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:41Z",
  "name": "don-quixote",
  "apps": {
    "total_memory_in_mb": 5120,
    "per_process_memory_in_mb": 1024,
    "total_instances": 10,
    "per_app_tasks": null
  },
  "services": {
    "paid_services_allowed": true,
    "total_service_instances": 10,
    "total_service_keys": 20
  },
  "routes": {
    "total_routes": 8,
    "total_reserved_ports": 20
  },
  "relationships": {
    "organization": {
      "data": {
        "guid": "9b370018-c38e-44c9-86d6-155c76801104"
      }
    },
    "spaces": {
      "data": [
        {
          "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
        }
      ]
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
    }
  }
}

This endpoint creates a new space quota scoped to a specific organization.

Definition

POST /v3/space_quotas

Required parameters

Name	Type	Description
name	string	Name of the quota.
relationships.organization	to-one relationship	A relationship to the organization where the quota belongs.

Optional parameters

Name	Type	Description	Default
apps	object	Quotas that affect applications and application sub-resources.
apps.per_process_memory_in_mb	integer or null	Maximum memory for a single process or task.	null (infinite)
apps.total_memory_in_mb	integer or null	Total memory allowed for all the started processes and running tasks in a space.	null (infinite)
apps.total_instances	integer or null	Total instances of all the started processes allowed in a space.	null (infinite)
apps.per_app_tasks	integer or null	Maximum number of running tasks in a single application.	null (infinite)
services	object	Quotas that affect services.
services.paid_services_allowed	boolean	Specifies whether instances of paid service plans can be created.	true
services.total_service_instances	integer or null	Total number of service instances allowed in a space.	null (infinite)
services.total_service_keys	integer or null	Total number of service keys allowed in a space.	null (infinite)
routes	object	Quotas that affect routes.
routes.total_routes	integer or null	Total number of routes allowed in a space.	null (infinite)
routes.total_reserved_ports	integer or null	Total number of ports that are reservable by routes in a space.	null (infinite)
relationships.spaces	to-many relationship	A relationship to the spaces where the quota is applied.

Permitted roles

Role	Notes
Admin
Org Manager	Org managers can create space quotas in their managed organizations.

Get a space quota

Example Request

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

Example Response

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

{
  "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:41Z",
  "name": "don-quixote",
  "apps": {
    "total_memory_in_mb": 5120,
    "per_process_memory_in_mb": 1024,
    "total_instances": 10,
    "per_app_tasks": null
  },
  "services": {
    "paid_services_allowed": true,
    "total_service_instances": 10,
    "total_service_keys": 20
  },
  "routes": {
    "total_routes": 8,
    "total_reserved_ports": 20
  },
  "relationships": {
    "organization": {
      "data": {
        "guid": "9b370018-c38e-44c9-86d6-155c76801104"
      }
    },
    "spaces": {
      "data": [
        {
          "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
        }
      ]
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
    }
  }
}

Definition

GET /v3/space_quotas/:guid

Permitted roles

Role	Notes
Admin
Admin Read-Only
Global Auditor
Org Manager	Can only query space quotas owned by affiliated organizations
Space Auditor	Can only query space quotas applied to affiliated spaces
Space Developer	Can only query space quotas applied to affiliated spaces
Space Manager	Can only query space quotas applied to affiliated spaces

Note: Response will not show any space guids that a user would not otherwise be able to see (see space view permissions).

List space quotas

Example Request

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

Example Response

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

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/space_quotas?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/space_quotas?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:41Z",
      "name": "don-quixote",
      "apps": {
        "total_memory_in_mb": 5120,
        "per_process_memory_in_mb": 1024,
        "total_instances": 10,
        "per_app_tasks": null
      },
      "services": {
        "paid_services_allowed": true,
        "total_service_instances": 10,
        "total_service_keys": 20
      },
      "routes": {
        "total_routes": 8,
        "total_reserved_ports": 20
      },
      "relationships": {
        "organizations": {
          "data": {
            "guid": "9b370018-c38e-44c9-86d6-155c76801104"
          }
        },
        "spaces": {
          "data": [
            {
              "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
            }
          ]
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
        },
        "organization": {
          "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
        }
      }
    },
    {
      "guid": "554bcf32-7032-4cb0-92bc-738f9d2089d3",
      "created_at": "2017-05-04T17:00:41Z",
      "updated_at": "2017-05-04T17:00:41Z",
      "name": "sancho-panza",
      "apps": {
        "total_memory_in_mb": 2048,
        "per_process_memory_in_mb": 1024,
        "total_instances": 5,
        "per_app_tasks": 2
      },
      "services": {
        "paid_services_allowed": true,
        "total_service_instances": 10,
        "total_service_keys": 20
      },
      "routes": {
        "total_routes": 8,
        "total_reserved_ports": 4
      },
      "relationships": {
        "organizations": {
          "data": {
            "guid": "9b370018-c38e-44c9-86d6-155c76801104"
          }
        },
        "spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/space_quotas/554bcf32-7032-4cb0-92bc-738f9d2089d3"
        },
        "organization": {
          "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
        }
      }
    }
  ]
}

This endpoint lists all space quota resources that the user has permission to view (see getting a space quota).

Definition

GET /v3/space_quotas

Name	Type	Description
guids	list of strings	Comma-delimited list of space quota guids to filter by.
names	list of strings	Comma-delimited list of space quota names to filter by.
organization_guids	list of strings	Comma-delimited list of organization guids 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.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Role
All Roles

Note: Space quotas in the response will not show any space guids that a user would not otherwise be able to see (see space view permissions).

Update a space quota

Example Request

curl "https://api.example.org/v3/space_quotas/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "don-quixote",
    "apps": {
      "total_memory_in_mb": 5120,
      "per_process_memory_in_mb": 1024,
      "total_instances": 10,
      "per_app_tasks": 5
    },
    "services": {
      "paid_services_allowed": true,
      "total_service_instances": 10,
      "total_service_keys": 20,
    },
    "routes": {
      "total_routes": 8,
      "total_reserved_ports": 4
    }
  }'

Example Response

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

{
  "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:41Z",
  "name": "don-quixote",
  "apps": {
    "total_memory_in_mb": 5120,
    "per_process_memory_in_mb": 1024,
    "total_instances": 10,
    "per_app_tasks": null
  },
  "services": {
    "paid_services_allowed": true,
    "total_service_instances": 10,
    "total_service_keys": 20
  },
  "routes": {
    "total_routes": 8,
    "total_reserved_ports": 20
  },
  "relationships": {
    "organization": {
      "data": {
        "guid": "9b370018-c38e-44c9-86d6-155c76801104"
      }
    },
    "spaces": {
      "data": [
        {
          "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
        }
      ]
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
    }
  }
}

This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values.

Definition

PATCH /v3/space_quotas/:guid

Optional parameters

Name	Type	Description
name	string	Name of the quota.
apps	object	Quotas that affect applications and application sub-resources.
apps.per_process_memory_in_mb	integer or null	Maximum memory for a single process or task.
apps.total_memory_in_mb	integer or null	Total memory of all the started processes and running tasks in a space.
apps.total_instances	integer or null	Total instances of all the started processes in a space.
apps.per_app_tasks	integer or null	Maximum number of running tasks in a single application.
services	object	Quotas that affect services.
services.paid_services_allowed	boolean	If instances of paid service plans can be created.
services.total_service_instances	integer or null	Total number of service instances in a space.
services.total_service_keys	integer or null	Total number of service keys in a space.
routes	object	Quotas that affect routes.
routes.total_routes	integer or null	Total number of routes that a space can have.
routes.total_reserved_ports	integer or null	Total number of ports that all routes in a space can reserve.

Permitted roles

Role	Notes
Admin
Org Manager	Can update space quotas in the organization where they have this role.

Delete a space quota

Space quotas cannot be deleted when applied to any spaces.

Example Request

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

Example Response

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

Definition

DELETE /v3/space_quotas/:guid

Permitted roles

Role	Notes
Admin
Org Manager	Can delete space quotas within their managed organizations.

Apply a space quota to a space

Example Request

curl "https://api.example.org/v3/space_quotas/:quota_guid/relationships/spaces" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "data": [{ "guid": "space-guid1" }, { "guid": "space-guid2" }]
}'

Example Response

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

  {
    "data": [
      { "guid": "space-guid1" },
      { "guid": "space-guid2" },
      { "guid": "previous-space-guid" }
    ],
    "links": {
      "self": { "href": "https://api.example.org/v3/space_quotas/quota-guid/relationships/spaces" }
    }
  }

This endpoint applies a space quota to one or more spaces.

Only an admin or an org manager in the quota’s parent organization can apply a space quota to a space.

Definition

POST /v3/space_quotas/:quota_guid/relationships/spaces

Required parameters

Name	Type	Description
data	to-many relationship	Space guids that the quota will apply to.

Permitted roles

Role	Notes
Admin
Org Manager	Can apply space quotas to spaces within their managed organizations.

Remove a space quota from a space

Example Request

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

Example Response

HTTP/1.1 204 No Content

This endpoint removes a space quota from a space.

Only an admin or an org manager in the quota’s parent organization can remove a space quota from a space.

Definition

DELETE /v3/space_quotas/:quota_guid/relationships/spaces/:space_guid

Permitted roles

Role	Notes
Admin
Org Manager	Can remove space quotas from spaces within their managed organizations.

Stacks

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

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

Stacks are not used for apps with a Docker lifecycle.

The stack object

Example Stack object

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

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

Create a stack

Example Request

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

Example Response

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

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

Definition

POST /v3/stacks

Required parameters

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

Optional parameters

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

Permitted roles

Admin

Get a stack

Example Request

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

Example Response

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

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

Definition

GET /v3/stacks/:guid

Permitted roles

All Roles

List stacks

Example Request

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

Example Response

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

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

Retrieve all stacks.

Definition

GET /v3/stacks

Query parameters

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

Permitted roles

All Roles

Update a stack

Example Request

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

Example Response

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

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

Definition

PATCH /v3/stacks/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Delete a stack

Example Request

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

Example Response

HTTP/1.1 204 No Content

Definition

DELETE /v3/stacks/:guid

Permitted roles

Admin

Tasks

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

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

The task object

Example Task object

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

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

Create a task

Example Request with Command

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

Example Request with Template Process

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

Example Response

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

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

Definition

POST /v3/apps/:guid/tasks

Required parameters

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

Optional parameters

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

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

Permitted roles

Admin
Space Developer

Get a task

Example Request

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

Example Response

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

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

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

Definition

GET /v3/tasks/:guid

Permitted roles

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

List tasks

Example Request

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

Example Response

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

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

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

Definition

GET /v3/tasks

Query parameters

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

Permitted roles

All Roles

List tasks for an app

Example Request

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

Example Response

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

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

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

Definition

GET /v3/apps/:guid/tasks

Query parameters

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

Permitted roles

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

Update a task

Example Request

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

Example Response

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

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

Definition

PATCH /v3/tasks/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Cancel a task

Example Request

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

Example Response

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

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

Cancels a running task.

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

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

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

Definition

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

Permitted roles

Admin
Space Developer

Users

Every Cloud Foundry action (pushing an application, creating a space) requires a user. Each Cloud Foundry installation has one pre-installed user, admin, which can create subsequent users. Users can be assigned roles which give them privileges to perform actions. For example, the Space Developer role grants a user permission to manage apps and services in a space (to push apps, scale apps, delete apps).

The user object

Example User object

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "metadata": {
      "labels": {},
      "annotations":{}
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Name	Type	Description
guid	uuid	Unique identifier for the user.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
username	string	The name registered in UAA. Will be null for UAA clients and non-UAA users.
presentation_name	string	The name displayed for the user. For UAA users, this is the same as the username. For UAA clients, this is the UAA client ID.
origin	string	The identity provider for the UAA user. Will be null for UAA clients.
links	links object	Links to related resources.
metadata.labels (experimental)	label object	Labels applied to the user.
metadata.annotations (experimental)	annotation object	Annotations added to the user.

Create a user

Creating a user requires one value, a GUID. This creates a user in the Cloud Controller database.

Generally, the GUID should match the GUID of an already-created user in the UAA database, though this is not required.

Example Request

curl "https://api.example.org/v3/users" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
  }'

Example Response

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

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "metadata": {
      "labels": {},
      "annotations":{}
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

POST /v3/users

Required parameters

Name	Type	Description
guid	string	Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user’s GUID. In the case of UAA clients, this will match the UAA client ID.
metadata.labels (experimental)	label object	Labels applied to the user.
metadata.annotations (experimental)	annotation object	Annotations added to the user.

Permitted roles

Role	Notes
Admin

Get a user

Example Request

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

Example Response

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

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "metadata": {
      "labels": {},
      "annotations":{}
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

GET /v3/users/:guid

Permitted roles

Roles	Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor	Can only view users affiliated with their org
Org Billing Manager	Can only view users affiliated with their org
Org Manager	Can only view users affiliated with their org
Space Auditor	Can only view users affiliated with their org
Space Developer	Can only view users affiliated with their org
Space Manager	Can only view users affiliated with their org

Note: A user can always see themselves with this endpoint, regardless of role.

List users

Example Request

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

Example Response

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/users?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/users?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/users?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
     {
      "guid": "client_id",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "username": null,
      "presentation_name": "client_id",
      "origin": null,
      "metadata": {
        "labels": {},
        "annotations":{}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
        }
      }
    },
    {
      "guid": "9da93b89-3f89-4f05-7238-8a2b123c79l9",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "username": "some-name",
      "presentation_name": "some-name",
      "origin": "uaa",
      "metadata": {
        "labels": {},
        "annotations":{}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9"
        }
      }
    }
  ]
}

Retrieve all users that the current user can see.

Definition

GET /v3/users

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of user guids to filter by.
usernames	list of strings	Comma-delimited list of usernames to filter by.
origins	list of strings	Comma-delimited list of user origins (user stores) to filter by. For example, users authenticated by UAA have the origin “uaa”; users authenticated by an LDAP provider have the origin “ldap”. When filtering by origins, usernames must be included.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Roles	Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor	Can only view users affiliated with their org
Org Billing Manager	Can only view users affiliated with their org
Org Manager	Can only view users affiliated with their org
Space Auditor	Can only view users affiliated with their org
Space Developer	Can only view users affiliated with their org
Space Manager	Can only view users affiliated with their org

Update a user

Update a user’s metadata.

Example Request

curl "https://api.example.org/v3/users/24d59a1e-2613-4255-86a2-e0454cc6e261" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
  "metadata": {
    "labels": { "enviroment": "production" },
    "annotations": { "note": "detailed information" }
  }'

Example Response

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

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "metadata": {
      "labels": { "enviroment": "production" },
      "annotations": { "note": "detailed information" }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

PATCH /v3/users

Required parameters

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

Permitted roles

Admin

Delete a user

All roles associated with a user will be deleted if the user is deleted.

Example Request

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

Example Response

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

Definition

DELETE /v3/users/:guid

Permitted roles

Role	Notes
Admin

Experimental Resources

App Manifest

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

The app manifest specification

Example Manifest

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

App-level configuration

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

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

Process-level configuration

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

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

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

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

Service-level configuration

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

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

Sidecar-level configuration

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

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

Generate an app manifest

Example Request

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

Example Response

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

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

Generate a manifest for an app and its underlying processes.

Definition

GET /v3/apps/:guid/manifest

Permitted Roles

Admin
Admin Read-Only
Space Developer

Apply an app manifest

Example Request

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

Example Response

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

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

Definition

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

Permitted Roles

Admin
Space Developer

App Restart

Restart an app

Example Request

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

Example Response

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

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

Definition

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

Permitted roles

Admin
Space Developer

Revisions

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

Revision are created when the following is changed:

• A new droplet is created for an app

• An app’s environment variables are changed

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

• An app rolls back to a prior revision

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

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

The revision object

Example Revision object

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

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

The process snapshot object

Example Process Snapshot object

{
  "web": {
    "command": "bundle exec rackup"
  },
  "worker": {
    "command": "bundle exec work"
  }
}

The process snapshot object is a map of process types to objects. Each object contains the command that the given process type was running at this revision.

The sidecar snapshot object

Example Sidecar Snapshot object

{
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300
}

Name	Type	Description
name	string	Human-readable name for the sidecar.
command	string	The command used to start the sidecar.
process_types	array of strings	A list of process types the sidecar applies to.
memory_in_mb	integer	Reserved memory for sidecar.

Get a revision

Example Request

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

Example Response

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

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

Definition

GET /v3/revisions/:guid

Permitted roles

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

List revisions for an app

Example Request

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

Example Response

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

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

Retrieve revisions for an app the user has access to.

Definition

GET /v3/apps/:guid/revisions

Query parameters

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

Permitted roles

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

List deployed revisions for an app

Example Request

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

Example Response

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

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

Retrieve deployed revisions for an app the user has access to. Deployed revisions are revisions that are linked to started processes in the app.

Definition

GET /v3/apps/:guid/revisions/deployed

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a revision

Example Request

curl "https://api.example.org/v3/revisions/[revguid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "processes": {
    "web": {
      "command": "bundle exec rackup"
    }
  },
  "sidecars": [
    {
      "name": "auth-sidecar",
      "command": "bundle exec sidecar",
      "process_types": ["web"],
      "memory_in_mb": 300
    }
  ],
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
    }
  }
}

Definition

PATCH /v3/revisions/:guid

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the revision.
metadata.annotations (experimental)	annotation object	Annotations applied to the revision.

Permitted roles

Admin
Space Developer

Security Groups

Security groups are collections of egress traffic rules that can be applied to the staging or running state of applications.

Security groups can either be applied globally or at the space-level.

Security groups can only allow (whitelist) traffic. They cannot be used to disallow (blacklist) traffic.

The security group object

Example Security Group object

{
  "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
  "created_at": "2020-02-20T17:42:08Z",
  "updated_at": "2020-02-20T17:42:08Z",
  "name": "my-group0",
  "globally_enabled": {
    "running": true,
    "staging": false
  },
  "rules": [
    {
      "protocol": "tcp",
      "destination": "10.10.10.0/24",
      "ports": "443,80,8080"
    },
    {
      "protocol": "icmp",
      "destination": "10.10.10.0/24",
      "type": 8,
      "code": 0,
      "description": "Allow ping requests to private services"
    }
  ],
  "relationships": {
    "staging_spaces": {
      "data": [
        { "guid": "space-guid-1" },
        { "guid": "space-guid-2" }
      ]
    },
    "running_spaces": {
      "data": []
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
    }
  }
}

Name	Type	Description
name	string	Name of the security group.
globally_enabled	object	Object that controls if the group is applied globally to the lifecycle of all applications.
globally_enabled.running	boolean	Specifies whether the group should be applied globally to all running applications.
globally_enabled.staging	boolean	Specifies whether the group should be applied globally to all staging applications.
rules	array of rule objects	Rules that will be applied by this security group.
relationships.staging_spaces	to-many relationship	A relationship to the spaces where the security_group is applied to applications during staging.
relationships.running_spaces	to-many relationship	A relationship to the spaces where the security_group is applied to applications during runtime.

The rule object

Name	Type	Description	Required	Default
protocol	string	Protocol type. Valid values are tcp, udp, icmp, or all	yes	N/A
destination	string	Destinations that the rule applies to. Valid CIDR, IP address, or IP address range	yes	N/A
ports	string	Ports that the rule applies to. Can be a single port (9000), a comma-separated list (9000,9001), or a range (9000-9200).	no	null
type	integer	Type required for ICMP protocol. Valid values are between -1 and 255 (inclusive)	no	null
code	integer	Code required for ICMP protocol. Valid values are between -1 and 255 (inclusive)	no	null
description	string	A description for the rule	no	null
log	boolean	Enable logging for rule	no	null

Create a security group

Example Request

curl "https://api.example.org/v3/security_groups" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
  "name": "my-group0",
  "rules": [
    {
      "protocol": "tcp",
      "destination": "10.10.10.0/24",
      "ports": "443,80,8080"
    },
    {
      "protocol": "icmp",
      "destination": "10.10.10.0/24",
      "type": 8,
      "code": 0,
      "description": "Allow ping requests to private services"
    }
  ]
}'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
  "created_at": "2020-02-20T17:42:08Z",
  "updated_at": "2020-02-20T17:42:08Z",
  "name": "my-group0",
  "globally_enabled": {
    "running": true,
    "staging": false
  },
  "rules": [
    {
      "protocol": "tcp",
      "destination": "10.10.10.0/24",
      "ports": "443,80,8080"
    },
    {
      "protocol": "icmp",
      "destination": "10.10.10.0/24",
      "type": 8,
      "code": 0,
      "description": "Allow ping requests to private services"
    }
  ],
  "relationships": {
    "staging_spaces": {
      "data": [
        { "guid": "space-guid-1" },
        { "guid": "space-guid-2" }
      ]
    },
    "running_spaces": {
      "data": []
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
    }
  }
}

Definition

POST /v3/security_groups

Required parameters

Name	Type	Description
name	string	Name of the security group.

Optional parameters

Name	Type	Description
globally_enabled	object	Object that controls if the group is applied globally to the lifecycle of all applications.
globally_enabled.running	boolean	Specifies whether the group should be applied globally to all running applications.
globally_enabled.staging	boolean	Specifies whether the group should be applied globally to all staging applications.
rules	array of rule objects	Rules that will be applied by this security group.
relationships.staging_spaces	to-many relationship	A relationship to the spaces where the security group is applied to applications during staging.
relationships.running_spaces	to-many relationship	A relationship to the spaces where the security group is applied to applications during runtime.

Permitted roles

Admin

Get a security group

Example Request

curl "https://api.example.org/v3/security_groups/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
  "created_at": "2020-02-20T17:42:08Z",
  "updated_at": "2020-02-20T17:42:08Z",
  "name": "my-group0",
  "globally_enabled": {
    "running": true,
    "staging": false
  },
  "rules": [
    {
      "protocol": "tcp",
      "destination": "10.10.10.0/24",
      "ports": "443,80,8080"
    },
    {
      "protocol": "icmp",
      "destination": "10.10.10.0/24",
      "type": 8,
      "code": 0,
      "description": "Allow ping requests to private services"
    }
  ],
  "relationships": {
    "staging_spaces": {
      "data": [
        { "guid": "space-guid-1" },
        { "guid": "space-guid-2" }
      ]
    },
    "running_spaces": {
      "data": []
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
    }
  }
}

Definition

GET /v3/security_groups/:guid

Permitted roles

Role	Notes
Admin	Can see all security groups
Admin Read-Only	Can see all security groups
Global Auditor	Can see all security groups
Org Auditor	Can see globally enabled security groups
Org Billing Manager	Can see globally enabled security groups
Org Manager	Can see globally enabled security groups or groups associated with a space they can see
Space Auditor	Can see globally enabled security groups or groups associated with a space they can see
Space Developer	Can see globally enabled security groups or groups associated with a space they can see
Space Manager	Can see globally enabled security groups or groups associated with a space they can see

List security groups

Example Request

curl "https://api.example.org/v3/security_groups" \
  -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/security_groups?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/security_groups?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
      "created_at": "2020-02-20T17:42:08Z",
      "updated_at": "2020-02-20T17:42:08Z",
      "name": "my-group0",
      "globally_enabled": {
        "running": true,
        "staging": false
      },
      "rules": [
        {
          "protocol": "tcp",
          "destination": "10.10.10.0/24",
          "ports": "443,80,8080"
        },
        {
          "protocol": "icmp",
          "destination": "10.10.10.0/24",
          "type": 8,
          "code": 0,
          "description": "Allow ping requests to private services"
        }
      ],
      "relationships": {
        "staging_spaces": {
          "data": [
            { "guid": "space-guid-1" },
            { "guid": "space-guid-2" }
          ]
        },
        "running_spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
        }
      }
    },
    {
      "guid": "a89a788e-671f-4549-814d-e34c1b2f533a",
      "created_at": "2020-02-20T17:42:08Z",
      "updated_at": "2020-02-20T17:42:08Z",
      "name": "my-group1",
      "globally_enabled": {
        "running": true,
        "staging": true
      },
      "rules": [],
      "relationships": {
        "staging_spaces": {
          "data": []
        },
        "running_spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a"
        }
      }
    }
  ]
}

Definition

GET /v3/security_groups

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of security group guids to filter by.
names	list of strings	Comma-delimited list of security group names to filter by.
globally_enabled_running	boolean	If true, only include the security groups that are enabled for running.
globally_enabled_staging	boolean	If true, only include the security groups that are enabled for staging.
running_space_guids	list of strings	Comma-delimited list of space guids to filter by.
staging_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.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Role	Notes
Admin	Can see all security groups
Admin Read-Only	Can see all security groups
Global Auditor	Can see all security groups
Org Auditor	Can see globally–enabled security groups
Org Billing Manager	Can see globally–enabled security groups
Org Manager	Can see globally–enabled security groups or groups associated with a space they can see
Space Auditor	Can see globally–enabled security groups or groups associated with a space they can see
Space Developer	Can see globally–enabled security groups or groups associated with a space they can see
Space Manager	Can see globally–enabled security groups or groups associated with a space they can see

List running security groups for a space

Example Request

curl "https://api.example.org/v3/spaces/[guid]/running_security_groups" \
  -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/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/running_security_groups?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/running_security_groups?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
      "created_at": "2020-02-20T17:42:08Z",
      "updated_at": "2020-02-20T17:42:08Z",
      "name": "my-group0",
      "globally_enabled": {
        "running": true,
        "staging": false
      },
      "rules": [
        {
          "protocol": "tcp",
          "destination": "10.10.10.0/24",
          "ports": "443,80,8080"
        },
        {
          "protocol": "icmp",
          "destination": "10.10.10.0/24",
          "type": 8,
          "code": 0,
          "description": "Allow ping requests to private services"
        }
      ],
      "relationships": {
        "staging_spaces": {
          "data": [
            { "guid": "space-guid-1" },
            { "guid": "space-guid-2" }
          ]
        },
        "running_spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
        }
      }
    },
    {
      "guid": "a89a788e-671f-4549-814d-e34c1b2f533a",
      "created_at": "2020-02-20T17:42:08Z",
      "updated_at": "2020-02-20T17:42:08Z",
      "name": "my-group1",
      "globally_enabled": {
        "running": true,
        "staging": true
      },
      "rules": [],
      "relationships": {
        "staging_spaces": {
          "data": []
        },
        "running_spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a"
        }
      }
    }
  ]
}

Definition

GET /v3/spaces/:guid/running_security_groups

Query parameters

Name	Type	Description
guids	list of strings	Comma-delimited list of security group guids to filter by.
names	list of strings	Comma-delimited list of security group 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.

Permitted roles

Role	Notes
Admin	Can see all security groups
Admin Read-Only	Can see all security groups
Global Auditor	Can see all security groups
Org Manager	Can see globally-enabled security groups and groups associated with spaces in their managed organizations
Space Auditor	Can see globally-enabled security groups and groups associated with spaces where they have this role
Space Developer	Can see globally-enabled security groups and groups associated with spaces where they have this role
Space Manager	Can see globally-enabled security groups and groups associated with spaces where they have this role

Service Bindings

Service bindings are relations between a service instance and an app; to use a service instance with an app, you must first bind them together.

Not all services support binding, as some services deliver value to users directly without integration with an application.

The service binding object

Example Service Binding object

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Name	Type	Description
type	string	Service binding type. Valid value is app.
data	object	Data returned from the service broker for the service instance. Valid values are credentials, syslog_drain_url and (experimental) volume_mounts.
guid	uuid	Unique identifier for the service binding.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
links	links object	Links to related resources.

Create a service binding

Example Request

curl "https://api.example.org/v3/service_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "app",
    "relationships": {
      "app": {
        "data": {
          "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      },
      "service_instance": {
        "data": {
          "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
        }
      }
    },
    "data": {
      "parameters": {
        "some_object_id": "for_the_service_broker"
      }
    }
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Definition

POST /v3/service_bindings

Required parameters

Name	Type	Description
type	string	Service binding type. Valid value is app.
relationships.app	to-one relationship	A relationship to an app.
relationships.service_instance	to-one relationship	A relationship to a service_instance.

Optional parameters

Name	Type	Description	Default
data.parameters	object	Additional configuration parameters for the service binding.	{}

Permitted roles

Admin
Space Developer

Get a service binding

Example Request

curl "https://api.example.org/v3/service_bindings/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Definition

GET /v3/service_bindings/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List service bindings

Example Request

curl "https://api.example.org/v3/service_bindings" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_bindings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "type": "app",
      "data": {
        "credentials": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "syslog_drain_url": "syslog://drain.url.example.org",
        "volume_mounts": []
      },
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        },
        "service_instance": {
          "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      }
    },
    {
      "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
      "type": "app",
      "data": {
        "credentials": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "syslog_drain_url": "syslog://drain.url.example.org",
        "volume_mounts": []
      },
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "service_instance": {
          "href": "https://api.example.org/v3/service_instances/8bf356j3-9e18-45b1-3333-124163f31f9e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      }
    }
  ]
}

This endpoint retrieves the service bindings the user has access to.

Definition

GET /v3/service_bindings

Query parameters

Name	Type	Description
app_guids	list of strings	Comma-delimited list of app guids to filter by.
service_instance_guids	list of strings	Comma-delimited list of service_instance guids to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

All Roles

Delete a service binding

Example Request

curl "https://api.example.org/v3/service_bindings/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

Definition

DELETE /v3/service_bindings/:guid

Permitted Roles

Admin
Space Developer

Service Brokers

Service brokers manage the lifecycle of services. On behalf of users, Cloud Controller will interact with service brokers to provision, get access to and manage access to the service offerings and plans they offer.

Admins can create and manage service brokers that are globally available, i.e., the service broker and its associated resources (service offerings and plans) can be made available to all users.

Space Developers can create and manage space-scoped service brokers. A space-scoped broker and its associated resources will only be available in the space the service broker was created.

The service broker object

Example Service Broker object

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "name": "my_service_broker",
  "url": "https://example.service-broker.com",
  "available": true,
  "status": "available",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "metadata": {
    "labels": {
      "type": "dev"
    },
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_offerings": {
      "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the service broker.
name	string	Name of the service broker.
url	string	URL of the service broker.
available	boolean	Whether or not the service broker is available.
status	string	Availability status of the service broker.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
relationships.space	to-one relationship	The space the service broker is restricted to. Omitted for globally available service brokers.
metadata.labels (experimental)	label object	Labels applied to the service broker.
metadata.annotations (experimental)	annotation object	Annotations added to the service broker.
links	links object	Links to related resources.

Create a service broker

Example Request

curl "https://api.example.org/v3/service_brokers" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_service_broker",
    "url": "https://example.service-broker.com",
    "authentication": {
      "type": "basic",
      "credentials": {
        "username": "us3rn4me",
        "password": "p4ssw0rd"
      }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  }'

Example Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint creates a new service broker and a job to synchronize the service offerings and service plans with those in the broker’s catalog. The Location header refers to the created job which syncs the broker with the catalog.

Definition

POST /v3/service_brokers

Required parameters

Name	Type	Description
name	string	Name of the service broker.
url	string	URL of the service broker.
authentication	authentication	Credentials used to authenticate against the service broker.

Optional parameters

Name	Type	Description
relationships.space	to-one relationship	If set, restricts the service broker to the specified space.
metadata.labels (experimental)	label object	Labels applied to the service broker.
metadata.annotations (experimental)	annotation object	Annotations applied to the service broker.

The authentication object

Name	Type	Description
type	string	Type of the authentication mechanisms that can be used. Valid value is basic.
credentials	object	Credentials for given authentication type.

Example basic authentication

{
  "type": "basic",
  "credentials": {
    "username": "admin",
    "password": "secretpassw0rd"
  }
}

Basic authentication credentials

Name	Type	Description
username	string	The username with which to authenticate against the service broker.
password	string	The password with which to authenticate against the service broker.

Permitted roles

Admin
Space Developer*

*Space Developers can only create space-scoped brokers. Space-scoped brokers can only be created when the space_scoped_private_broker_creation feature flag is true.

Get a service broker

Example Request

curl "https://api.example.org/v3/service_brokers/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "name": "my_service_broker",
  "url": "https://example.service-broker.com",
  "available": true,
  "status": "available",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "metadata": {
    "labels": {
      "type": "dev"
    },
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_offerings": {
      "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

This endpoint retrieves the service broker by GUID.

Definition

GET /v3/service_brokers/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Space Developer (only space-scoped brokers)

List service brokers

Example Request

curl "https://api.example.org/v3/service_brokers" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_brokers?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "name": "my_service_broker",
      "url": "https://example.service-broker.com",
      "available": true,
      "status": "available",
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "relationships": {} ,
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        },
        "service_offerings": {
          "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        }
      }
    },
    {
      "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
      "name": "another_service_broker",
      "url": "https://another-example.service-broker.com",
      "available": true,
      "status": "available",
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "relationships": {
        "space": {
          "data": {
            "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_brokers/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "service_offerings": {
          "href": "https://api.example.org/v3/service_offerings?service_broker_guids=7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  ]
}

This endpoint retrieves the service brokers the user has access to.

Definition

GET /v3/service_brokers

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of service broker names to filter by.
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
space_guids	list of strings	Comma-delimited list of space GUIDs to filter by.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, name.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Space Developer (only space-scoped brokers)

Update a service broker

Example Request

curl "https://api.example.org/v3/service_brokers/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_service_broker",
    "url": "https://example.service-broker.com",
    "authentication": {
      "type": "basic",
      "credentials": {
        "username": "us3rn4me",
        "password": "p4ssw0rd"
      }
    },
    "metadata": {
      "labels": {"key": "value"},
      "annotations": {"note": "detailed information"}
    }
  }'

Example Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint updates a broker and creates a job to synchronize the service offerings and service plans with those in the broker’s catalog. The Location header refers to the created job which syncs the broker with the catalog. Service Brokers that are in the process of being synchronized or deleted cannot be updated.

Definition

PATCH /v3/service_brokers/[guid]

Optional parameters

Name	Type	Description
name	string	Name of the service broker.
url	string	URL of the service broker.
authentication	authentication	Credentials used to authenticate against the service broker.
metadata.labels (experimental)	label object	Labels applied to the service broker.
metadata.annotations (experimental)	annotation object	Annotations applied to the service broker.

The authentication object

Name	Type	Description
type	string	Type of the authentication mechanisms that can be used. Valid value is basic.
credentials	object	Credentials for given authentication type.

Example basic authentication

{
  "type": "basic",
  "credentials": {
    "username": "admin",
    "password": "secretpassw0rd"
  }
}

Basic authentication credentials

Name	Type	Description
username	string	The username with which to authenticate against the service broker.
password	string	The password with which to authenticate against the service broker.

Permitted roles

Admin
Space Developer (only space-scoped brokers)

Delete a service broker

Example Request

curl "https://api.example.org/v3/service_brokers/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint creates a job to delete an existing service broker. The Location header refers to the created job.

Definition

DELETE /v3/service_brokers/:guid

Permitted roles

Admin
Space Developer (only space-scoped brokers)

Service Offerings

Service Offerings represent the services offered by Service Brokers. A Service Broker will have one or more Service Offerings. A Service Offering will have one or more Service Plans. Service Offerings and Service Plans are created and updated when a Service Broker is registered or updated.

Visibility of Service Offerings

This table shows the Service Offerings that different roles can see. The Service Offerings that a user can see relate to their Space and Organization roles, regardless of which Space or Organization is being targeted.

A Service Offering can be seen when at least one of its Service Plans can be seen. Service Plans may be configured to be Public, or they may be configured with a relationship to a restricted list of Organizations.

Service Offerings and Service Plans from a space-scoped Service Broker cannot have their visibility configured. They are only visible to members of that Space.

Role	Public Plans	Restricted Plans	From space-scoped Service Brokers
Admin	All	All	All
Admin Read	All	All	All
Global Auditor	All	All	All
Org Manager	All	In Organisation	None
Org Auditor	All	In Organisation	None
Org Billing	All	In Organisation	None
Space Manager	All	In Organisation	In Space
Space Developer	All	In Organisation	In Space
Space Auditor	All	In Organisation	In Space
Unauthenticated	All*	None	None

*Unless the hide_marketplace_from_unauthenticated_users feature flag is true

The Service Offering object

Example Service Offering object

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_service_offering",
  "description": "Provides my service",
  "available": true,
  "tags": ["relational", "caching"],
  "requires": [],
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "shareable": true,
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "shareable": true
    },
    "features": {
      "plan_updateable": true,
      "bindable": true,
      "instances_retrievable": true,
      "bindings_retrievable": true,
      "allow_context_updates": false
    }
  },
  "relationships": {
    "service_broker": {
      "data": {
        "name": "my_service_broker",
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_plans": {
      "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_broker": {
      "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the Service Offering.
name	string	Name of the Service Offering.
description	string	Description of the Service Offering.
available	boolean	Whether or not the Service Offering is available.
tags	list of strings	Descriptive tags for the Service Offering.
requires	list_of_strings	A list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are syslog_drain, route_forwarding and volume_mount.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.
shareable	boolean	Whether or not Service Instances of this Service Offering can be shared across Organizations and Spaces.
broker_catalog	object	This object contains information obtained from the Service Broker Catalog.
broker_catalog.id	string	The identifier that the Service Broker provided for this Service Offering.
broker_catalog.metadata	object	Additional information provided by the Service Broker.
broker_catalog.features.plan_updateable	boolean	Whether the Service Offering supports upgrade/downgrade for Service Plans by default
broker_catalog.features.bindable	boolean	Specifies whether Service Instances of the service can be bound to applications.
broker_catalog.features.instances_retrievable	boolean	Specifies whether the Fetching a Service Instance endpoint is supported for all Service Plans.
broker_catalog.features.bindings_retrievable	boolean	Specifies whether the Fetching a Service Binding endpoint is supported for all Service Plans.
broker_catalog.features.allow_context_updates	boolean	Specifies whether Service Instance updates relating only to context are propagated to the Service Broker.
relationships.service_broker	to-one relationship	The Service Broker that provides this Service Offering.
metadata.labels (experimental)	label object	Labels applied to the Service Offering.
metadata.annotations (experimental)	annotation object	Annotations added to the Service Offering.
links	links object	Links to related resources.

Get a Service Offering

Example Request

curl "https://api.example.org/v3/service_offerings/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_service_offering",
  "description": "Provides my service",
  "available": true,
  "tags": ["relational", "caching"],
  "requires": [],
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "shareable": true,
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "shareable": true
    },
    "features": {
      "plan_updateable": true,
      "bindable": true,
      "instances_retrievable": true,
      "bindings_retrievable": true,
      "allow_context_updates": false
    }
  },
  "relationships": {
    "service_broker": {
      "data": {
        "name": "my_service_broker",
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_plans": {
      "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_broker": {
      "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    }
  }
}

This endpoint retrieves the service offering by GUID.

Definition

GET /v3/service_offerings/:guid

Permitted roles

All Roles
Unauthenticated Users

List service offerings

Example Request

curl "https://api.example.org/v3/service_offerings" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_offerings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_offerings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_offerings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
      "name": "my_service_offering",
      "description": "Provides my service",
      "available": true,
      "tags": ["relational", "caching"],
      "requires": [],
      "created_at": "2019-11-28T13:44:02Z",
      "updated_at": "2019-11-28T13:44:02Z",
      "shareable": true,
      "broker_catalog": {
        "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
        "metadata": {
          "shareable": true
        },
        "features": {
          "plan_updateable": true,
          "bindable": true,
          "instances_retrievable": true,
          "bindings_retrievable": true,
          "allow_context_updates": false
        }
      },
      "relationships": {
        "service_broker": {
          "data": {
            "name": "my_service_broker",
            "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
        },
        "service_plans": {
          "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
        },
        "service_broker": {
          "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
        }
      }
    },
    {
      "guid": "20e6cd62-12bb-11ea-90d1-7bfec2c75bcd",
      "name": "other_service_offering",
      "description": "Provides another service",
      "available": true,
      "tags": ["caching"],
      "requires": [],
      "created_at": "2019-11-29T16:44:02Z",
      "updated_at": "2019-11-29T16:44:02Z",
      "shareable": true,
      "broker_catalog": {
        "id": "3cb11822-12bb-11ea-beb1-a350dc7453b9",
        "metadata": {
          "shareable": true
        },
        "features": {
          "plan_updateable": true,
          "bindable": true,
          "instances_retrievable": true,
          "bindings_retrievable": true,
          "allow_context_updates": false
        }
      },
      "relationships": {
        "service_broker": {
          "data": {
            "name": "my_service_broker",
            "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_offerings/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
        },
        "service_plans": {
          "href": "https://api.example.org/v3/service_plans?service_offering_guids=20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
        },
        "service_broker": {
          "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
        }
      }
    }
  ]
}

This endpoint retrieves the service offerings the user has access to.

Definition

GET /v3/service_offerings

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of names to filter by.
available	boolean	Filter by the available property. Valid values are true or false.
service_broker_guids	list of strings	Comma-delimited list of Service Broker GUIDs to filter by.
service_broker_names	list of strings	Comma-delimited list of Service Broker names to filter by.
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.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles
Unauthenticated Users

Update a service offering

Example Request

curl "https://api.example.org/v3/service_offerings/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "metadata": {
      "labels": {"key": "value"},
      "annotations": {"note": "detailed information"}
    }
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_service_offering",
  "description": "Provides my service",
  "available": true,
  "tags": ["relational", "caching"],
  "requires": [],
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "shareable": true,
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "shareable": true
    },
    "features": {
      "plan_updateable": true,
      "bindable": true,
      "instances_retrievable": true,
      "bindings_retrievable": true,
      "allow_context_updates": false
    }
  },
  "relationships": {
    "service_broker": {
      "data": {
        "name": "my_service_broker",
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_plans": {
      "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_broker": {
      "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    }
  }
}

This endpoint updates a Service Offering with labels and annotations.

Definition

PATCH /v3/service_offerings/[guid]

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the service offering.
metadata.annotations (experimental)	annotation object	Annotations applied to the service offering.

Permitted roles

Admin
Space Developer (only for service offerings from space-scoped brokers)

Delete a service offering

Example Request

curl "https://api.example.org/v3/service_offerings/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

This endpoint deletes a Service Offering. This is typically used to remove orphan Service Offerings from the Cloud Foundry database when they have been removed from the Service Broker catalog, or when the Service Broker has been removed.

Note that this operation only affects the Cloud Foundry database, and no attempt is made to contact the Service Broker.

Definition

DELETE /v3/service_offerings/:guid

Query parameters

Name	Type	Description
purge	boolean	If true, any service plans, instances, and bindings associated with this service offering will also be deleted.

Permitted roles

Admin
Space Developer (only service offerings from space-scoped brokers)

Service Plans

Service Plans represent the service plans offered by a Service Offering. A Service Offering will have one or more Service Plans. Service Offerings and Service Plans are created and updated when a Service Broker is registered or updated.

The Service Plan object

Example Service Plan object

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_big_service_plan",
  "description": "Big",
  "visibility_type": "public",
  "available": true,
  "free": false,
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "maintenance_info": {
    "version": "1.0.0+dev4",
    "description": "Database version 7.8.0"
  },
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "custom-key": "custom-information"
    },
    "maximum_polling_duration": null,
    "features": {
      "plan_updateable": true,
      "bindable": true
    }
  },
  "schemas": {
    "service_instance": {
      "create": {
        "parameters": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "billing-account": {
              "description": "Billing account number used to charge use of shared fake server.",
              "type": "string"
            }
          }
        }
      },
      "update": {}
    },
    "service_binding": {
      "create": {}
    }
  },
  "relationships": {
    "service_offering": {
      "data": {
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
    },
    "service_offering": {
      "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    },
    "visibility": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the Service Plan.
name	string	Name of the Service Plan.
description	string	Description of the Service Plan.
available	boolean	Whether or not the Service Plan is available.
visibility_type	string	Denotes the visibility of the plan. Can be public, admin, organization, space. See list of visibility types.
free	boolean	Whether or not the Service Plan is free of charge.
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.
maintenance_info	object	Maintenance information for a Service Instance which is provisioned using this Service Plan.
maintenance_info.version	semver	Maintenance information about the version of this Service Plan. This field is used to determine whether a maintenance update is available for a Service Instance.
maintenance_info.description	string	Description of the impact of this maintenance update, for example, important version changes, configuration changes, default value changes, etc.
broker_catalog	object	This object contains information obtained from the Service Broker Catalog.
broker_catalog.id	string	The identifier that the Service Broker provided for this Service Plan.
broker_catalog.metadata	object	Additional information provided by the Service Broker.
broker_catalog.maximum_polling_duration	integer	The maximum number of seconds that Cloud Foundry will wait for an asynchronous Service Broker operation.
broker_catalog.features.plan_updateable	boolean	Whether the Service Plan supports upgrade/downgrade for Service Plans by default
broker_catalog.features.bindable	boolean	Specifies whether Service Instances of the service can be bound to applications.
schemas	object	Schema definitions for Service Instances and Service Bindings for the Service Plan.
schemas.service_instance.create	object	Schema definition for Service Instance creation.
schemas.service_instance.create.parameters	JSON Schema object	The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object.
schemas.service_instance.update	object	Schema definition for Service Instance update.
schemas.service_instance.update.parameters	JSON Schema object	The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object.
schemas.service_binding.create	object	Schema definition for Service Binding creation.
schemas.service_binding.create.parameters	JSON Schema object	The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object.
relationships.service_offering	to-one relationship	The Service Offering that this Service Plan relates to.
relationships.space	to-one relationship	The Space of the Service Broker, if this Service Plan is from a Space-Scoped Service Broker.
metadata.labels (experimental)	label object	Labels applied to the Service Plan.
metadata.annotations (experimental)	annotation object	Annotations added to the Service Plan.
links	links object	Links to related resources.

Get a Service Plan

Example Request

curl "https://api.example.org/v3/service_plans/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_big_service_plan",
  "description": "Big",
  "visibility_type": "public",
  "available": true,
  "free": false,
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "maintenance_info": {
    "version": "1.0.0+dev4",
    "description": "Database version 7.8.0"
  },
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "custom-key": "custom-information"
    },
    "maximum_polling_duration": null,
    "features": {
      "plan_updateable": true,
      "bindable": true
    }
  },
  "schemas": {
    "service_instance": {
      "create": {
        "parameters": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "billing-account": {
              "description": "Billing account number used to charge use of shared fake server.",
              "type": "string"
            }
          }
        }
      },
      "update": {}
    },
    "service_binding": {
      "create": {}
    }
  },
  "relationships": {
    "service_offering": {
      "data": {
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
    },
    "service_offering": {
      "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    },
    "visibility": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
    }
  }
}

This endpoint retrieves the service plan by GUID.

Definition

GET /v3/service_plans/:guid

Permitted roles

All Roles
Unauthenticated Users (for public plans, unless hide_marketplace_from_unauthenticated_users is set)

List service plans

Example Request

curl "https://api.example.org/v3/service_plans" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_plans?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_plans?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_plans?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
      "name": "my_big_service_plan",
      "description": "Big plan",
      "visibility_type": "organization",
      "available": true,
      "free": false,
      "created_at": "2019-11-28T13:44:02Z",
      "updated_at": "2019-11-28T13:44:02Z",
      "maintenance_info": {
        "version": "1.0.0+dev4",
        "description": "Database version 7.8.0"
      },
      "broker_catalog": {
        "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
        "metadata": {
          "custom-key": "custom-value"
        },
        "maximum_polling_duration": null,
        "features": {
          "plan_updateable": true,
          "bindable": true
        }
      },
      "schemas": {
        "service_instance": {
          "create": {
            "parameters": {
              "$schema": "http://json-schema.org/draft-04/schema#",
              "type": "object",
              "properties": {
                "billing-account": {
                  "description": "Billing account number used to charge use of shared fake server.",
                  "type": "string"
                }
              }
            }
          },
          "update": {}
        },
        "service_binding": {
          "create": {}
        }
      },
      "relationships": {
        "service_offering": {
          "data": {
            "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
        },
        "service_offering": {
          "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
        },
        "visibility": {
          "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
        }
      }
    },
    {
      "guid": "20e6cd62-12bb-11ea-90d1-7bfec2c75bcd",
      "name": "other_service_plan",
      "description": "Provides another service plan",
      "visibility_type": "admin",
      "available": true,
      "free": false,
      "created_at": "2019-11-29T16:44:02Z",
      "updated_at": "2019-11-29T16:44:02Z",
      "maintenance_info": {},
      "broker_catalog": {
        "id": "3cb11822-12bb-11ea-beb1-a350dc7453b9",
        "metadata": {
          "other-data": true
        },
        "maximum_polling_duration": null,
        "features": {
          "plan_updateable": true,
          "bindable": true
        }
      },
      "schemas": {
        "service_instance": {
          "create": {},
          "update": {}
        },
        "service_binding": {
          "create": {}
        }
      },
      "relationships": {
        "service_offering": {
          "data": {
            "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_plans/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
        },
        "service_offering": {
          "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
        },
        "visibility": {
          "href": "https://api.example.org/v3/service_plans/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd/visibility"
        }
      }
    }
  ]
}

This endpoint retrieves the service plans the user has access to.

Definition

GET /v3/service_plans

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of names to filter by.
available	boolean	Filter by the available property. Valid values are true or false.
broker_catalog_id	list of strings	Comma-delimited list of IDs provided by the Service Broker for the Service Plan 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.
service_broker_guids	list of strings	Comma-delimited list of Service Broker GUIDs to filter by.
service_broker_names	list of strings	Comma-delimited list of Service Broker names to filter by.
service_offering_guids	list of strings	Comma-delimited list of Service Offering GUIDs to filter by.
service_offering_names	list of strings	Comma-delimited list of Service Offering names to filter by.
service_instance_guids	list of strings	Comma-delimited list of Service Instance GUIDs to filter by.
label_selector	string	Experimental - A query string containing a list of label selector requirements.

The organization_guids and space_guids filters do not filter plans that are public. They both act on plans that are restricted to certain Organizations, and to plans from Space-Scoped Service Brokers.

Permitted roles

All Roles
Unauthenticated Users (for public plans, unless hide_marketplace_from_unauthenticated_users is set)

Update a service plan

Example Request

curl "https://api.example.org/v3/service_plans/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "metadata": {
      "labels": {"key": "value"},
      "annotations": {"note": "detailed information"}
    }
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_big_service_plan",
  "description": "Big",
  "visibility_type": "public",
  "available": true,
  "free": false,
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "maintenance_info": {
    "version": "1.0.0+dev4",
    "description": "Database version 7.8.0"
  },
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "custom-key": "custom-information"
    },
    "maximum_polling_duration": null,
    "features": {
      "plan_updateable": true,
      "bindable": true
    }
  },
  "schemas": {
    "service_instance": {
      "create": {
        "parameters": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "billing-account": {
              "description": "Billing account number used to charge use of shared fake server.",
              "type": "string"
            }
          }
        }
      },
      "update": {}
    },
    "service_binding": {
      "create": {}
    }
  },
  "relationships": {
    "service_offering": {
      "data": {
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
    },
    "service_offering": {
      "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    },
    "visibility": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
    }
  }
}

This endpoint updates a Service Plan with labels and annotations.

Definition

PATCH /v3/service_plans/[guid]

Optional parameters

Name	Type	Description
metadata.labels (experimental)	label object	Labels applied to the service plan.
metadata.annotations (experimental)	annotation object	Annotations applied to the service plan.

Permitted roles

Admin
Space Developer (only for service plans from space-scoped brokers)

Delete a Service Plan

Example Request

curl "https://api.example.org/v3/service_plans/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

This endpoint deletes a Service Plan. This is used to remove Service Plans from the Cloud Foundry database when they have are no longer provided by the Service Broker.

Definition

DELETE /v3/service_plans/:guid

Permitted roles

Admin
Space Developer (only service plans from space-scoped brokers)

Service Plan Visibility

Service Plan Visibility is used to manage whether a role has access to a given Service Plan and its Service Offering.

The Service Plan Visibility object

Example Service Plan Visibility object - Organization restricted

{
  "type": "organization",
  "organizations": [
    {
      "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
      "name": "my_org"
    }
  ]
}

Example Service Plan Visibility object - Space restricted

{
  "type": "space",
  "space": {
    "guid": "ab7eb420-11e5-11ea-b7db-4b5d5e7975ad",
    "name": "my_space"
  }
}

Name	Type	Description
type	string	Denotes the visibility of the plan. Can be public, admin, organization, space. See list of visibility types.
space.guid	string	Unique identifier for the space whose members can access the plan. Present if type is space.
space.name	string	Name of the space whose members can access the plan. Present if type is space.
organizations	array of organization object	List of organizations whose members can access the plan. Present if type is organization.

The organization visibility object

Name	Type	Description
guid	string	Unique identifier for the organization where the plan is available.
name	string	Name of the organization where the plan is available.

List of visibility types

Name	Description
public	Everyone, including unauthenticated users can see the Service Plan.
admin	Only Admin, Admin Read-Only and Global Auditor can see the Service Plan.
organization	Restricted to members of a set of Organizations.
space	Restricted to members of a Space. Only possible if the Plan comes from a space-scoped Service Broker.

Get a Service Plan Visibility

Example Request

curl "https://api.example.org/v3/service_plans/[guid]/visibility" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "public"
}

This endpoint retrieves the service plan visibility for a given plan.

Definition

GET /v3/service_plans/:guid/visibility

Permitted roles

All Roles

Update a Service Plan Visibility

Example Request

curl "https://api.example.org/v3/service_plans/[guid]/visibility" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "organization",
    "organizations": [
      { "guid" : "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482" }
    ]
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "organization",
  "organizations": [
    {
      "guid": "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482",
      "name": "other_org"
    }
  ]
}

This endpoint updates a Service Plan Visibility. It behaves similar to the POST Service Plan Visibility endpoint but this endpoint will replace the existing list of organizations when the Service Plan is organization visible.

Definition

PATCH /v3/service_plans/[guid]/visibility

Parameters

Name	Type	Description
type	string	Denotes the visibility of the plan. Can be public, admin, organization. See list of visibility types.
organizations	array of objects	Desired list of organizations GUIDs where the plan will be accessible. Required if type is organization.

Permitted roles

Admin

Apply a Service Plan Visibility

Example Request

curl "https://api.example.org/v3/service_plans/[guid]/visibility" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "organization",
    "organizations": [
      { "guid": "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482" }
    ]
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "organization",
  "organizations": [
    {
      "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
      "name": "my_org"
    },
    {
      "guid": "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482",
      "name": "other_org"
    }
  ]
}

This endpoint applies a Service Plan Visibility. It behaves similar to the PATCH Service Plan Visibility endpoint but this endpoint will append to the existing list of organizations when the Service Plan is organization visible.

Definition

POST /v3/service_plans/[guid]/visibility

Parameters

Name	Type	Description
type	string	Denotes the visibility of the plan. Can be public, admin, organization. See list of visibility types.
organizations	array of objects	Desired list of organizations GUIDs where the plan will be accessible. Required if type is organization.

Permitted roles

Admin

Remove Organization from a Service Plan Visibility

Example Request

curl "https://api.example.org/v3/service_plans/[guid]/visibility/[organization_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

This endpoint removes an Organization from a Service Plan Visibility list of Organizations. It is only defined for Service Plans which are org-restricted. It will fail with a HTTP Status Code of 422 for any other visibility type (e.g. Public).

Definition

DELETE /v3/service_plans/[guid]/visibility/[organization_guid]

Permitted roles

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,
  "origin": "user",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Name	Type	Description
guid	uuid	Unique identifier for the sidecar.
name	string	Human-readable name for the sidecar.
command	string	The command used to start the sidecar.
process_types	array of strings	A list of process types the sidecar applies to.
memory_in_mb	integer	Reserved memory for sidecar.
origin	string	Specifies whether the sidecar was created by the user or via the buildpack.
relationships.app	to-one relationship	The app the sidecar is associated with.
created_at	datetime	The time with zone when the object was created.
updated_at	datetime	The time with zone when the object was last updated.

Create a sidecar associated with an app

Example Request

curl "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/sidecars" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "auth-sidecar",
    "command": "bundle exec rackup",
    "process_types": ["web", "worker"],
    "memory_in_mb": 300
  }'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "origin": "user",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

POST /v3/apps/:guid/sidecars

Required parameters

Name	Type	Description
name	string	Human-readable name for the sidecar.
command	string	The command used to start the sidecar.
process_types	array of strings	A list of process types the sidecar applies to.

Optional parameters

Name	Type	Description
memory_in_mb	integer	Reserved memory for sidecar.

Permitted roles

Admin
Space Developer

Get a sidecar

Example Request

curl "https://api.example.org/v3/sidecars/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "origin": "user",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

GET /v3/sidecars/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a sidecar

Example Request

curl "https://api.example.org/v3/sidecars/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auth-sidecar",
    "command": "bundle exec rackup",
    "process_types": ["web", "worker"],
    "memory_in_mb": 300
  }'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "origin": "user",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

PATCH /v3/sidecars/:guid

Optional parameters

Name	Type	Description
name	string	Human-readable name for the sidecar.
command	string	The command used to start the sidecar.
process_types	array of strings	A list of process types the sidecar applies to.
memory_in_mb	integer	Reserved memory for sidecar.

Permitted roles

Admin
Space Developer

List sidecars for app

Example Request

curl "https://api.example.org/v3/apps/[guid]/sidecars" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "name": "auth-sidecar",
      "command": "bundle exec rackup",
      "process_types": ["web", "worker"],
      "memory_in_mb": 300,
      "origin": "user",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z"
    },
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
      "name": "echo-sidecar",
      "command": "start-echo-server",
      "process_types": ["web"],
      "memory_in_mb": 300,
      "origin": "user",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:59Z",
      "updated_at": "2017-02-01T01:33:59Z"
    }
  ]
}

Retrieves all sidecars associated with a app.

Definition

GET /v3/apps/:guid/sidecars

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List sidecars for process

Example Request

curl "https://api.example.org/v3/processes/[guid]/sidecars" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "name": "auth-sidecar",
      "command": "bundle exec rackup",
      "process_types": ["web", "worker"],
      "memory_in_mb": 300,
      "origin": "user",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z"
    },
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
      "name": "echo-sidecar",
      "command": "start-echo-server",
      "process_types": ["web"],
      "memory_in_mb": 300,
      "origin": "user",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:59Z",
      "updated_at": "2017-02-01T01:33:59Z"
    }
  ]
}

Retrieves all sidecars associated with a process.

Definition

GET /v3/processes/:guid/sidecars

Query parameters

Name	Type	Description
page	integer	Page to display. Valid values are integers >= 1.
per_page	integer	Number of results per page. Valid values are 1 through 5000.
order_by	string	Value to sort by. Defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Delete a sidecar

Example Request

curl "https://api.example.org/v3/sidecars/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

Definition

DELETE /v3/sidecars/:guid

Permitted roles

Admin
Space Developer

Space Manifest

The space manifest is a method for applying bulk configurations to apps and their underlying processes.

The space manifest specification

Example Manifest

---
applications:
- name: app1
  buildpacks:
  - ruby_buildpack
  - java_buildpack
  env:
    VAR1: value1
    VAR2: value2
  routes:
  - route: route.example.com
  - route: another-route.example.com
  services:
  - my-service1
  - my-service2
  - name: my-service-with-arbitrary-params
    parameters:
      key1: value1
      key2: value2
  stack: cflinuxfs3
  metadata:
    annotations:
      contact: "[email protected] [email protected]"
    labels:
      sensitive: true
  processes:
  - type: web
    command: start-web.sh
    disk_quota: 512M
    health-check-http-endpoint: /healthcheck
    health-check-type: http
    health-check-invocation-timeout: 10
    instances: 3
    memory: 500M
    timeout: 10
  - type: worker
    command: start-worker.sh
    disk_quota: 1G
    health-check-type: process
    instances: 2
    memory: 256M
    timeout: 15
- name: app2
  env:
    VAR1: value1
  processes:
  - type: web
    instances: 1
    memory: 256M
  sidecars:
  - name: authenticator
    process_types: [ 'web', 'worker' ]
    command: bundle exec run-authenticator
    memory: 800M

  - name: upcaser
    process_types: [ 'worker' ]
    command: ./tr-server
    memory: 2G

Space-level configuration

Field	Description
applications	An array of App configurations

App-level configuration

This configuration is specified at the top-level and applies to all of the app’s processes.

Field	Description
buildpacks	Must be an Array. a) An empty array, which will automatically select the appropriate default buildpack according to the coding language. b) An array of one or more URLs pointing to buildpacks. c) An array of one or more installed buildpack names. Replaces the legacy buildpack field.
docker	If present, the created app will have Docker lifecycle type. The value of this key is ignored by the API but may be used by clients to source the registry address of the image and credentials, if needed. The generate manifest endpoint will return the registry address of the image and username provided with this key.
env	A key-value hash of environment variables to be used for the app when running.
no-route	Boolean value. When set to true, any routes specified with the routes attribute will be ignored and any existing routes will be removed; ignored if false.
processes	List of configurations for individual process types. See Process-level configuration.
random-route	Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified.
default-route	Boolean value. If true, a route for the app will be created using the app name as the hostname and the containing organization’s default domain as the domain. If false, if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored and results in noop.
routes	An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path
services	An array of service-instances to bind to the app. See Service-level configuration.
sidecars	An array of configurations for individual sidecars. See Sidecar-level configuration.
stack	The root filesystem to use with the buildpack, for example cflinuxfs3.
metadata.labels (experimental)	Labels applied to the app.
metadata.annotations (experimental)	Annotations applied to the app.
buildpack	DEPRECATED in favor of the buildpacks field above. a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language. b) A URL pointing to a buildpack. c) Name of an installed buildpack.

Process-level configuration

This configuration is for the individual process. Each process is created if it does not already exist.

With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.

If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.

Field	Description
type	(Required) Process type. The identifier for the processes to be configured.
command	The command used to start the process. This overrides start commands from Procfiles and buildpacks.
disk_quota	The disk limit for all instances of the web process. This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
health-check-http-endpoint	Endpoint called to determine if the app is healthy.
health-check-invocation-timeout	The timeout in seconds for individual health check requests for http and port health checks.
health-check-type	Type of health check to perform. none is deprecated and an alias to process.
instances	The number of instances to run.
memory	The memory limit for all instances of the web process. This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
timeout	Time in seconds at which the health-check will report failure.

Service-level configuration

This configuration is creating new service bindings between the app and a service instance. The services field can take either an array of service instance name strings or an array of the following service-level fields.

Field	Description
name	(Required) Service instance name. The name of the service instance to be bound to.
parameters	A map of arbitrary key/value pairs to send to the service broker during binding.

Sidecar-level configuration

This configuration is for the individual sidecar. Each sidecar is created if it does not already exist.

Field	Description
name	(Required) Sidecar name. The identifier for the sidecars to be configured.
command	The command used to start the sidecar.
process_types	List of processes to associate sidecar with.
memory	Memory in mb that the sidecar will be allocated.

Apply a space manifest

Example Request

curl "https://api.example.org/v3/spaces/[guid]/actions/apply_manifest" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/x-yaml" \
  --data-binary @/path/to/manifest.yml

Example Response

HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Apply changes specified in a manifest to the named apps and their underlying processes. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.

Definition

POST /v3/spaces/:guid/actions/apply_manifest

Permitted roles

Admin
Space Developer

Upgrade Guide

This document is intended to help client authors upgrade from Cloud Foundry’s V2 API to the V3 API.

When moving to the V3 API, it is important to understand that the V3 API is backed by the same data as the V2 API. Though resources may be presented differently and have different interaction patterns, the internal state of CF will be the same across both APIs.

If you have questions, need help, or want to chat about the upgrade process, please reach out to us in Cloud Foundry Slack.

Changed Resources

This table shows how V2 resources map to their respective V3 counterparts. Note that some V2 resources have split into multiple V3 resources, and some V2 resources have been combined into a single resource on V3. As these resources are currently under active development, these mappings may change.

V2 Resource(s)	V3 Resource(s)	Details
Apps	Apps, Builds, Droplets, Packages, Processes
Buildpacks	Buildpacks
Domains, Shared Domains, Private Domains	Domains	Domains in V3
Environment Variable Groups	Environment Variable Groups
Events	Audit Events
Feature Flags	Feature Flags
Jobs	Jobs
Organizations	Organizations
Quota Definitions	Organization Quotas	Organization Quotas in V3
Resource Matches	Resource Matches
Routes, Route Mappings	Routes	Routes in V3
Security Groups	Security Groups
Service Bindings, Service Keys	Service Keys
Service Brokers	Service Brokers
Service Instances, User-Provided Service Instances	Service Instances
Spaces	Spaces
Space Quota Definitions	Space Quotas	Space Quotas in V3
Stacks	Stacks
Usage Events	Usage Events
Users	Roles, Users	Users and Roles in V3

Domains in V3

In V2, there were two types of domains exposed via different endpoints: private domains and shared domains.

In V3, there is only one domain resource. A domain is “shared” if it has an “owning organization”, which is the organization in which the domain is accessible. This is represented as a relationship to this organization. A domain is “private” if it doesn’t have this relationship.

Read more about the domain resource.

Organization Quotas in V3

In V2, -1 represented an unlimited value for a quota limit.

In V3, null is used to represent an unlimited value.

The names of the limit fields have changed from V2 to V3.

V2	V3
non_basic_services_allowed	services.paid_services_allowed
total_services	services.total_service_instances
total_service_keys	services.total_service_keys
total_routes	routes.total_routes
total_reserved_route_ports	routes.total_reserved_ports
total_private_domains	domains.total_domains
memory_limit	apps.total_memory_in_mb
instance_memory_limit	apps.per_process_memory_in_mb
app_instance_limit	apps.total_instances
app_task_limit	apps.per_app_tasks

Read more about the organization quota resource.

Routes in V3

In V2, the route resource represented a URL that could be mapped to an app, and the route mapping resource represented a mapping between a route and an app.

In V3, these concepts have been collapsed into a single route resource. Now, a route can have one or more “destinations” listed on it. These represent a mapping from the route to a resource that can serve traffic (e.g. a process of an app).

Read more about routes and destinations.

Space Quotas in V3

In V2, -1 represented an unlimited value for a quota limit.

In V3, null is used to represent an unlimited value.

The names of the limit fields have changed from V2 to V3.

V2	V3
non_basic_services_allowed	services.paid_services_allowed
total_services	services.total_service_instances
total_service_keys	services.total_service_keys
total_routes	routes.total_routes
total_reserved_route_ports	routes.total_reserved_ports
memory_limit	apps.total_memory_in_mb
instance_memory_limit	apps.per_process_memory_in_mb
app_instance_limit	apps.total_instances
app_task_limit	apps.per_app_tasks

Read more about the space quota resource.

Users and Roles in V3

The user resource remains largely unchanged from the v2 API. On v2, GET /v2/users was restricted to admins, and other users needed to use nested endpoints (GET /v2/organizations/:guid/user and GET /v2/spaces/:guid/user) to view user resources. On v3, GET /v3/users is now available for all users, similar to other resources. Note that this does not change what user resources are visible.

In V2, roles were modeled as associations between organization and space endpoints. In V3, roles have a dedicated resource: /v3/roles. This has changed the manner in which roles are assigned. For example, in V2, to assign a user the org_manager role, one would PUT /v2/organizations/:org_guid/managers/:user_id. In V3, one would POST /v3/roles with the role type and relationships to the user and organization.

Read more about users and roles.

Conceptual Changes

App Sub-Resources

The V2 API rolls up several resources into its representation of an “app”:

1. Packages: Source assets for the application
2. Droplets: Staged, executable assets for the application
3. Builds: Configuration for how to stage the package into a droplet
4. Processes: Configuration for how to run the droplet

The V3 API exposes these resources on the API to provide more visibility and enable more complicated workflows. For example:

1. Staging a previous package into a new droplet
2. Rolling back to a previous droplet
3. Staging a droplet to run a task, without running any processes
4. Running multiple different processes from a single droplet (for example: a web process and a worker process)

Here are some examples of implications for clients:

1. The app resource contains much less information about the application as a whole
2. An application can have multiple processes, each with their own start command, scale, and stats
3. An application might not be running with its most recent package or droplet

Asynchronous Operations

Unlike V2, clients cannot opt-in for asynchronous responses from endpoints. Instead, endpoints that require asynchronous processing will return 202 Accepted with a Location header pointing to the job resource to poll. Endpoints that do not require asynchronous processing will respond synchronously.

For clients that want to report the outcome of an asynchronous operation, the expected pattern is to poll the job in the Location header until its state is no longer PROCESSING. If the job’s state is FAILED, the errors field will contain any errors that occurred during the operation.

An example of an asynchronous endpoint is the delete app endpoint.

Read more about the job resource.

Errors

Example Request

curl "https://api.example.org/v2/apps/not-found" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 404 Not Found
Content-Type: application/json

{
   "description": "The app could not be found: not-found",
   "error_code": "CF-AppNotFound",
   "code": 100004
}

Example Request

curl "https://api.example.org/v3/apps/not-found" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 404 Not Found
Content-Type: application/json

{
   "errors": [
      {
         "detail": "App not found",
         "title": "CF-ResourceNotFound",
         "code": 10010
      }
   ]
}

The V3 API returns an array of errors instead of a single error like in V2.

Clients may wish to display all returned errors.

Filtering

Filters are specified as individual query parameters in V3

curl "https://api.example.org/v2/apps?q=name+IN+dora,broker;stack:cflinuxfs3" \
  -X GET \
  -H "Authorization: bearer [token]"

curl "https://api.example.org/v3/apps?names=dora,broker&stacks=cflinuxfs3" \
  -X GET \
  -H "Authorization: bearer [token]"

Filtering resources no longer uses V2’s query syntax. See the example to the right.

A few common filters have been also renamed in V3:

V2 filter	V3 filter
results-per-page	per_page
page	page
order-by	order_by
order-direction	N/A1

¹ In V3, order is ascending by default. Prefix the order_by value with - to make it descending. For example, ?order_by=-name would order a list of resources by name in descending order.

Read more about filtering in V3.

Including Associated Resources

The inline-relations-depth parameter is no longer supported on V3. Instead, some resources support the include parameter to selectively include associated resources in the response body.

For example, to include an app’s space in the response: cf curl /v3/apps/:guid?include=space

Read more about the include parameter.

New Concepts

Actions

Actions are API requests that are expected to immediately initiate change within the Cloud Foundry runtime. This is differentiated from requests which update a record but require additional updates, such as restarting an app, to cause changes to a resource to take effect.

Example: POST /v3/apps/:guid/actions/start

Links

Example Request

curl "https://api.example.org/v3/apps/:guid" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

{
  "...": "...",
  "links": {
    "self": {
      "href": "http://api.example.com/v3/apps/:guid"
    },
    "space": {
      "href": "http://api.example.com/v3/spaces/:space_guid"
    }
  }
}

Links provide URLs to associated resources, relationships, and actions for a resource. The example links to both the app itself and the space in which it resides.

Metadata

Example Request

curl "https://api.example.org/v3/:resource/:guid" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

{
  "...": "...",
  "metadata": {
    "labels": {
      "environment": "production",
      "internet-facing": "false"
    },
    "annotations": {
      "contacts": "Bill tel(1111111) email(bill@fixme)"
    }
  }
}

Metadata allows you to tag and query certain API resources with information; metadata does not affect the resource’s functionality.

For more details and usage examples, see metadata or official CF docs.

Note that metadata consists of two keys, labels and annotations, each of which consists of key-value pairs. API V3 allows filtering by labels (see label_selector) but not by annotations.

Relationships

Example Request

curl "https://api.example.org/v3/apps" \
  -X POST \
  -H "Authorization: bearer [token]"
  -d '{
        "name": "testapp",
        "relationships": {
         "space": { "data": { "guid": "1234" }}
        }
      }'

Relationships represent associations between resources: For example, every space belongs in an organization, and every app belongs in a space. The V3 API can create, read, update, and delete these associations.

In the example request we create an app with a relationship to a specific space.

One can retrieve or update a resource’s relationships. For example, to retrieve an app’s relationship to its space with the /v3/apps/:app_guid/relationships/space endpoint.

For more information, refer to the relationships.

New Resources

The V3 API introduces new resources that are not available on the V2 API. Below are brief descriptions of these resources. This is not intended to be an exhaustive list and may not be updated as new resources are added to V3.

Note: Some of these resources may still be experimental and are subject to change or removal without warning. For up to date information on which resources are still experimental see Experimental Resources.

App Features

App features support enabling/disabling behaviors for an individual app.

Read more about the app feature resource.

Deployments

Deployments are objects that manage updates to applications with zero downtime.

Read more about the deployment resource.

Isolation Segments

Isolation segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.

Read more about the isolation segment resource.

Manifests

Manifests are a method for providing bulk configuration to applications and other resources in a space.

Read more about the app manifest and space manifest resources.

Revisions

Revisions represent code and configuration used by an application at a specific time. The most recent revision for a running application represents the code and configuration currently running in Cloud Foundry.

Read more about the revision resource.

Sidecars

Sidecars are additional programs that are run in the same container as a process.

Read more about the sidecar resource.

Tasks

Tasks are one-off jobs that are intended to execute a droplet, stop, and be cleaned up, freeing up resources.

Examples of this include database migrations and running batch jobs.

Read more about the task resource.

Useful Links

1. V3 API Proposals
2. CAPI (Cloud Controller API) Slack Channel