Introduction

Overview

Welcome to the Cloud Foundry V3 API docs! Version 3 adds 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
• Changing application source code without stopping the app via deployments

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 available 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	timestamp	The ISO8601 compatible date and time when resource was created
updated_at	timestamp	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": "POST"
}

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 OAuth 2 token with user roles that are managed by the API.

OAuth 2 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_controller.update_build_state	This scope allows its bearer to update the state of a build; currently only used when updating builds

Cloud Foundry user roles

Users that interact with the API should have one or more of these roles. Some of them (e.g. admin) are controlled via scopes on the user’s token. Others (e.g. space developer) are controlled via the roles resource.

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 an 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

Component roles

Components that interact with the Cloud Controller in the back-end can be given these roles to allow limited access to API resources. These roles are controlled via scopes on the component’s token.

Role	Description
Build State Updater	Allows a component to update the state of build resources; OAuth token must contain cloud_controller.update_build_state scope

Errors

Example Error

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

An error response will always return a list of error objects. Errors appear on the job resource for asynchronous operations.

The error object

Clients should use the code and title fields for programmatically handling specific errors. The message in the detail field is subject to change over time.

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

Common errors

These are some of the more common errors returned by many endpoints.

Title	Code	HTTP Status	Description
CF-BadQueryParameter	10005	400	An invalid query parameter was given
CF-InvalidAuthToken	1000	401	An invalid auth token was given
CF-NotAuthenticated	10002	401	No auth token was given, but authentication is required for this endpoint
CF-NotAuthorized	10003	403	The authenticated user does not have permission to perform this operation
CF-ResourceNotFound	10010	404	The specified resource does not exist, or the authenticated user cannot read it
CF-UnprocessableEntity	10008	422	Catch-all error when an operation fails to complete; the detail field will contain more information
UnknownError	10001	500	An unexpected, uncaught error occurred; the CC logs will contain more information

Fields

The fields parameter allows clients to fetch resources and include information of parent objects in the response. It works in a similar way to include, but the response only displays the requested fields rather than the entire resource.

For example, a response to /v3/service_instances/:guid?fields[space.organization]=name will contain detailed information about the service instance, as well as the name of the organization it belongs to.

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

The fields query parameter may also grant visibility to parts of resources where the whole resource is not visible. For instance, the name of an organization may be retrieved with fields, where the whole organization resource may not be visible.

Fields parameter

The fields parameter is structured as: fields[resource]=keys&fields[parent.resource]=other,keys

• resource is the name of the resource being requested, qualified by the relationship to the current resource. For example /v3/service_instances?fields[space]=name where space is a direct relationship of a service instance, or /v3/service_instances?fields[space.organization]=name where organization is a relationship of space.
• keys is a comma-separated list of the fields in the object being requested. For example, /v3/service_instances?fields[space]=name,guid will return just the name and guid of the space in the includes section.

For information on fields support for each resource refer to its documentation.

Resources with Fields

Resource	Endpoint
Service Instances	v3/service_instances, v3/service_instances/:guid
Shared Spaces	/v3/service_instances/:guid/relationships/shared_spaces
Service Offerings	v3/service_offerings, v3/service_offerings/:guid
Service Plans	v3/service_plans, v3/service_plans/:guid

Fields Sample requests

Example request to service instances resource to include parent orgs and spaces

curl "https://api.example.org/v3/service_instances?fields[space]=name,guid,relationships.organization&fields[space.organization]=name,guid" \
  -X GET \
  -H "Authorization: bearer [token]"

Example response

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

Filters

Endpoints which return lists of resources also support filtering the returned resources using query parameters. Each resource’s list endpoint documents the allowed filters for that endpoint. For details about the syntax of query parameters in general, see 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.

In the case of audit events, multiple timestamps can be requested, which will return all audit events that occurred at those timestamps. In the following request, all audit events that occurred New Year’s just before midnight and July 4th at noon will be returned:

GET /v3/audit_events?created_ats=2019-12-31T23:59:59Z,2020-07-04T12:00:00Z

Exception

The label_selector query parameter will act as AND function, not an OR.

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?hosts=hostname1,,hostname2

This will return all routes with hostname "hostname1", "" OR "hostname2".

Relational Operators (Experimental)

Some fields (e.g. created_at and updated_at) can be filtered using relational operators when listing resources.

For example, a response to GET /v3/audit_events?created_ats[lt]=2020-06-30T12:34:56Z will contain audit events with a created_at timestamp strictly earlier than 2020-06-30T12:34:56Z.

Multiple relational operators can be combined to further refine the listed resources. For example, a response to GET /v3/audit_events?created_ats[lt]=2020-01-02T00:00:00Z&created_ats[gt]=2019-12-31T23:59:59Z will return all audit events occurring on New Year’s Day.

Timestamps must be in standard timestamp format.

Valid relational operators

Operator	Description
lt	Return resources strictly less than the given value for the filtered attribute
lte	Return resources less than or equal to the given value for the filtered attribute
gt	Return resources strictly greater than the given value for the filtered attribute
gte	Return resources greater than or equal to the given value for the filtered attribute

Exclusion Operator (Experimental)

Some fields support filtering on all values except a given set of values.

For example, a response to GET /v3/audit_events?target_guids[not]=guid-1,guid-2 will contain audit events with a target.guid not equal to guid-1 nor guid-2.

Operator	Description
not	Return resources not equal to the given value(s) for the filtered attribute

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, space.organization, space
routes/[:guid]	domain, space.organization, space
service_plans	space.organization, service_offering
service_plans/[:guid]	space.organization, service_offering
service_credential_bindings	app, service_instance
service_credential_bindings/[:guid]	app, service_instance
service_route_bindings	route, service_instance
service_route_bindings/[:guid]	route, service_instance
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,
     "...": "..."
   },
   "resources": [
      {
         "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
         "name": "app1",
         "...": "..."
      },
      {
         "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
         "name": "app2",
         "...": "..."
      }
   ],
   "included": {
      "spaces": [
         {
            "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
            "name": "space1",
            "...": "..."
         },
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space2",
            "...": "..."
         }
      ],
      "organizations": [
         {
            "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
            "name": "org1",
            "...": "..."
         },
         {
            "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
            "name": "org2",
            "...": "..."
         }
      ]
   }
}

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",
            "...": "..."
         }
      ]
   }
}

Lifecycles

Lifecycles inform the platform of how to build droplets and run apps. For example, 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, kpack
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 for VMs. 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.

Note: This lifecycle is not supported on Cloud Foundry for Kubernetes.

Buildpack lifecycle object

Name	Type	Description
type	string	buildpack
data.buildpacks	list of strings	A list of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack during staging
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 pre-built 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 {}

Kpack lifecycle

Example Kpack Lifecycle

{
  "type": "kpack",
  "data": {
    "buildpacks": ["paketo-buildpacks/java"]
  }
}

This is the default lifecycle for Cloud Foundry for Kubernetes. When staging an app with this lifecycle, the app source code will be built into an OCI image using a Cloud Native Buildpack and kpack. This image is published to the app image registry and a docker lifecycle droplet is created referring to the image.

When running an app with this lifecycle, a container is created and the OCI image is executed inside of it.

Note: This lifecycle is not supported on Cloud Foundry for VMs.

Kpack lifecycle object

Name	Type	Description
type	string	kpack
data.buildpacks	list of strings	An optional list of buildpack names. Specify an empty list to auto-detect a suitable buildpack during staging

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.

When a service instance is being created, the service broker is sent the annotations of the service instance, and the space and organization in which the service instance reside. When a service instance is being updated, the service broker is sent the annotations of the space and organization in which the service instance reside. When a service binding is being created, the service broker is sent annotations of any associated app, and the space and organization in which the binding resides. Only annotations with a prefix are sent.

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 keys

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.

An annotation key prefix must adhere to the following restrictions:

• Length: 0-253 characters
• Allowed characters: a-z, A-Z, 0-9, -, and .; emojis cannot be used in keys
• DNS subdomain format (series of subdomain annotations separated by .)

An annotation key name must adhere to the following restrictions:

• Length: 1-63 characters
• Allowed characters: a-z, A-Z, 0-9, -, _, and .; emojis cannot be used in keys
• Must begin and end with an alphanumeric character

Annotation values

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.

Specifying processes in manifest files

Custom process types can also be configured via a manifest file. Read more about manifests. It is not recommended to specify processes in both a manifest and a Procfile for the same app.

Query Parameters

Clients can assume that query parameters on the API will always follow these rules:

• Parameter names (before the =, and ignoring any modifiers like [gt]) will only contain characters a-z (lowercase) and -.
• When a parameter accepts multiple values, these will be represented as a comma-delimited list of strings (see filters).

Because commas are used to separate list entries, parameter values that contain commas must be percent-encoded. For example, to retrieve apps named either a,b or c,d, the request would look like GET /v3/apps?names=a%2Cb,c%2Cd. Note that the commas within the app names are encoded (as %2C), but the comma separating the two app names is not. If a client is encoding the whole query string before sending it to the API, the commas within the app names will end up double-encoded.

Relationships

Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not.

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 demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships.

Endpoints that return relationship data list this information under the relationships key.

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; see asynchronous operations
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

Timestamps

Timestamps generally appear in created_at and updated_at fields on resources. Precision beyond seconds is not supported, even if the underlying database supports it (e.g. Postgres). As a result, filtering on sub-second timestamps is not allowed.

All v3 timestamps have the following format YYYY-MM-DDThh:mm:ssZ.

Example timestamp (June 30, 2020 at 11:49:04 PM UTC): 2020-06-30T23:49:04Z

Updating Actual State

The Cloud Controller is primarily responsible for the desired state of apps and processes. Most endpoints will only update the desired states of your apps and processes within Cloud Controller in order to provide users with the opportunity to incur zero downtime when updating apps. Restarting the app will be required for the desired state changes to become the actual state.

The stats endpoint can be used at any time to determine the actual (running) state of a process, and by proxy, an app.

Endpoints that will affect runtime

The following endpoints will immediately impact the runtime of the app, and the desired changes will take effect without needing to restart the app.

Endpoint
PATCH /v3/spaces/:guid/features/ssh
DELETE /v3/routes/:guid/destinations/:destination_guid

The following endpoints will immediately impact runtime and take effect when only the instances field is updated. If any other fields are updated, the app will need to be restarted in order for any desired changes to take effect, including instance count changes.

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

The following endpoints will immediately impact runtime and the desired changes will take effect if the specified fields are not included in the request.

If the field is specified, the app will need to be restarted in order for any desired changes to take effect.

Endpoint	Changes requiring a restart
POST /v3/routes/:guid/destinations	Adding a destination with a port
PATCH /v3/routes/:guid/destinations	Replacing the port field Note: If the port is specified, this endpoint will unmap any route not listed in the body but will not map any of the new routes in the request body. For this reason we caution against using the endpoint in most circumstances. A combination of adding ports and removing ports will better fit most use cases.

All other changes will not take effect on running apps until they are restarted.

Warnings

Example Warnings

{
  "warnings": [
    {
      "detail": "something went wrong"
    }
  ]
}

Warnings appear on the job resource.

The warning object

Name	Type	Description
detail	string	Description of the warning

Resources

Admin

These endpoints are only for admin users.

Clear buildpack cache

Example Request

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

Example Response

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

This endpoint will delete all of the existing buildpack caches in the blobstore. The buildpack cache is used during staging by buildpacks as a way to cache certain resources, e.g. downloaded Ruby gems. An admin who wants to decrease the size of their blobstore could use this endpoint to delete unnecessary blobs.

Definition

POST /v3/admin/actions/clear_buildpack_cache

Permitted Roles

Admin

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
guid	uuid	Unique identifier for the app
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
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
relationships.space	to-one relationship	The space the app is contained in
metadata.labels	label object	Labels applied to the app
metadata.annotations	annotation object	Annotations added to the app
links	links object	Links to related resources

Create an app

Example Request

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

Example Response

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

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STOPPED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "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	label object	Labels applied to the app
metadata.annotations	annotation object	Annotations applied to the app

Potential errors (experimental)

In addition to any common errors, this endpoint may return the following errors.

Title	Code	HTTP Status	Description
CF-UniquenessError	10016	422	The given app name is already taken in the targeted space
CF-FeatureDisabled	330002	403	Some feature flag must be enabled by the Cloud Foundry admin in order to push the app as is. The detail message should contain information on which feature is disabled.

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	list of strings	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, state
label_selector	string	A query string containing a list of label selector requirements
lifecycle_type	string	Lifecycle type to filter by; valid values are buildpack, docker
include	list of strings	Optionally include a list of unique related resources in the response; valid values are space and spaceorganization
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	label object	Labels applied to the app
metadata.annotations	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"
      },
    "download": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
    }
  },
  "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",
          "binding_id": "0e85b634-e043-4b43-96da-f83dfe83ab33",
          "binding_name": "db-for-my-app",
          "instance_id": "07fca01c-f789-4d45-80b4-e19ba3ca862c",
          "instance_name": "my-mysql-service",
          "label": "mysql",
          "tags": ["relational", "sql"],
          "plan": "xlarge",
          "credentials": {
            "username": "user",
            "password": "top-secret"
           },
          "syslog_drain_url": "https://syslog.example.org/drain",
          "volume_mounts": [],
          "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

Get permissions

Example Request

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

Example Response

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

{
  "read_basic_data": true,
  "read_sensitive_data": false
}

Get the current user’s permissions for the given app. If a user can see an app, then they can see its basic data. Only admin, read-only admins, and space developers can read sensitive data.

Definition

GET /v3/apps/:guid/permissions

Permitted roles

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

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

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": {}
  }
}

This endpoint will synchronously stop and start an application. Unlike the start and stop actions, this endpoint will error if the app is not successfully stopped in the runtime.

For restarting applications without downtime, see the deployments resource.

Definition

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

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",
      "enabled": false
    }
  ],
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
    "last": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
    "next": null,
    "previous": null
  }
}

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

Definition

GET /v3/apps/:guid/features

Permitted roles

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

Update an app feature

Example Request

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

Example Response

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Space Developer

App Usage Events

App usage events are a record of changes in the usage of apps and tasks. Examples include starting an application, scaling an application (from, say, one to three instances), and stopping an application.

Usage events are typically used by billing and chargeback applications.

The app usage event object

Example App Usage Event object

{
  "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
  "created_at": "2020-05-28T16:41:23Z",
  "updated_at": "2020-05-28T16:41:26Z",
  "state": {
    "current": "STARTED",
    "previous": "STOPPED"
  },
  "app": {
    "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
    "name": "name-1982"
  },
  "process": {
    "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
    "type": "type-1983"
  },
  "space": {
    "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
    "name": "name-1664"
  },
  "organization": {
    "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
  },
  "buildpack": {
    "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
    "name": "label-64"
  },
  "task": {
    "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
    "name": "name-2929"
  },
  "memory_in_mb_per_instance": {
    "current": 512,
    "previous": 256
  },
  "instance_count": {
    "current": 10,
    "previous": 5
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the event
created_at	timestamp	The time with zone when the event occurred
updated_at	timestamp	Identical to created_at (events are created, never updated)
state.current	string or null	Current state of the app that this event pertains to, if applicable
state.previous	string or null	Previous state of the app that this event pertains to, if applicable
app.guid	string or null	Unique identifier of the app that this event pertains to, if applicable
app.name	string or null	Name of the app that this event pertains to, if applicable
process.guid	string or null	Unique identifier of the process that this event pertains to, if applicable
process.type	string or null	Type of the process that this event pertains to, if applicable
space.guid	string or null	Unique identifier of the space that this event pertains to, if applicable
space.name	string or null	Name of the space that this event pertains to, if applicable
organization.guid	string or null	Unique identifier of the org that this event pertains to, if applicable
buildpack.guid	string or null	Unique identifier of the buildpack that this event pertains to, if applicable
buildpack.name	string or null	Name of the buildpack that this event pertains to, if applicable
task.guid	string or null	Unique identifier of the task that this event pertains to, if applicable
task.name	string or null	Name of the task that this event pertains to, if applicable
memory_in_mb_per_instance.current	integer or null	Current memory in MB of the app that this event pertains to, if applicable
memory_in_mb_per_instance.previous	integer or null	Previous memory in MB of the app that this event pertains to, if applicable
instance_count.current	integer or null	Current instance count of the app that this event pertains to, if applicable
instance_count.previous	integer or null	Previous instance count of the app that this event pertains to, if applicable
links	links object	Links to related resources

Get an app usage event

Example Request

curl "https://api.example.org/v3/app_usage_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": "2020-05-28T16:41:23Z",
  "updated_at": "2020-05-28T16:41:26Z",
  "state": {
    "current": "STARTED",
    "previous": "STOPPED"
  },
  "app": {
    "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
    "name": "name-1982"
  },
  "process": {
    "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
    "type": "type-1983"
  },
  "space": {
    "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
    "name": "name-1664"
  },
  "organization": {
    "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
  },
  "buildpack": {
    "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
    "name": "label-64"
  },
  "task": {
    "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
    "name": "name-2929"
  },
  "memory_in_mb_per_instance": {
    "current": 512,
    "previous": 256
  },
  "instance_count": {
    "current": 10,
    "previous": 5
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
    }
  }
}

Retrieve an app usage event.

Definition

GET /v3/app_usage_events/:guid

Permitted Roles

Admin
Admin Read-Only
Global Auditor

List app usage events

Example Request

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

Example Response

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

{
  "pagination": {
    "total_results": 2,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/app_usage_events?page=1&per_page=1"
    },
    "last": {
      "href": "https://api.example.org/v3/app_usage_events?page=2&per_page=1"
    },
    "next": {
      "href": "https://api.example.org/v3/app_usage_events?page=2&per_page=1"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
      "created_at": "2020-05-28T16:41:23Z",
      "updated_at": "2020-05-28T16:41:26Z",
      "state": {
        "current": "STARTED",
        "previous": "STOPPED"
      },
      "app": {
        "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
        "name": "name-1982"
      },
      "process": {
        "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
        "type": "type-1983"
      },
      "space": {
        "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
        "name": "name-1664"
      },
      "organization": {
        "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
      },
      "buildpack": {
        "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
        "name": "label-64"
      },
      "task": {
        "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
        "name": "name-2929"
      },
      "memory_in_mb_per_instance": {
        "current": 512,
        "previous": 256
      },
      "instance_count": {
        "current": 10,
        "previous": 5
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
        }
      }
    }
  ]
}

Retrieve all app usage events the user has access to.

Definition

GET /v3/app_usage_events

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 value is created_at
after_guid	string	Filters out events before and including the event with the given guid
guids	list of strings	Comma-delimited list of usage event guids to filter by
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

Permitted Roles

All Roles

Purge and seed app usage events

Example Request

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

Example Response

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

Destroys all existing events. Populates new usage events, one for each started app. All populated events will have a created_at value of current time. There is the potential race condition if apps are currently being started, stopped, or scaled. The seeded usage events will have the same guid as the app.

Definition

POST /v3/app_usage_events/actions/destructively_purge_all_and_reseed

Permitted Roles

Admin

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
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
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. Also supports filtering by exclusion.
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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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"
  },
  "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"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the build
created_at	timestamp	The time with zone when the build was created
updated_at	timestamp	The time with zone when the build was last updated
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.guid	string	The package that is the input to the staging process
droplet.guid	string	A resulting droplet from the staging process; droplet will be null if staging has not completed
created_by.guid	object	The guid of the user that created the build
created_by.name	object	The name of the user that created the build
created_by.email	object	The email of the user that created the build
relationships.app	to-one relationship	The app the build belongs to
metadata.labels	label object	Labels applied to the build
metadata.annotations	annotation object	Annotations applied to the build
links	links object	Links to related resources

Create a build

Example Request

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

Example Response

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

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGING",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "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
staging_memory_in_mb	integer	Memory in MB allocated for staging of the build
staging_disk_in_mb	integer	Disk space in MB allocated for staging of the build
metadata.labels	label object	Labels applied to the build
metadata.annotations	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"
  },
  "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"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
    }
  }
}

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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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"
  },
  "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"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
    }
  }
}

Definition

PATCH /v3/builds/:guid

Optional parameters

Name	Type	Description
metadata.labels	label object	Labels applied to the build
metadata.annotations	annotation object	Annotations applied to the build
state (experimental)	string	Build status; valid values are FAILED or STAGED (field can only be passed by Build State Updaters)
lifecycle.data.image (experimental)	string	Image reference tag where the built complete image was stored (field can only be passed by Build State Updaters)

Permitted roles

Role	Notes
Admin
Space Developer
Build State Updater	This is a special component role; read more about component roles

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	timestamp	The time with zone when the object was created
updated_at	timestamp	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
stack	string	The name of the stack that the buildpack will use
filename	string	The filename of the buildpack
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
metadata.labels	label object	Labels applied to the app
metadata.annotations	annotation object	Annotations added to the app
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	label object	Labels applied to the buildpack
metadata.annotations	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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	label object	Labels applied to the buildpack
metadata.annotations	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",
  "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"
    },
    "cancel": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
      "method": "POST"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the deployment
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
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
droplet.guid	string	The droplet guid that the deployment is transitioning the app to
previous_droplet.guid	string	The app’s current droplet guid 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
relationships.app	to-one relationship	The app the deployment is updating
metadata.labels	label object	Labels applied to the deployment
metadata.annotations	annotation object	Annotations applied to the deployment
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",
  "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"
    },
    "cancel": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
      "method": "POST"
    }
  }
}

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	label object	Labels applied to the deployment
metadata.annotations	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",
  "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"
    },
    "cancel": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
      "method": "POST"
    }
  }
}

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",
      "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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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",
  "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"
    },
    "cancel": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
      "method": "POST"
    }
  }
}

Definition

PATCH /v3/deployments/:guid

Optional parameters

Name	Type	Description
metadata.labels	label object	Labels applied to the deployment
metadata.annotations	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,
  "router_group": null,
  "supported_protocols": ["http"],
  "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	timestamp	The time with zone when the object was created
updated_at	timestamp	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
router_group.guid	uuid	The guid of the desired router group to route tcp traffic through; if set, the domain will only be available for tcp traffic
supported_protocols	list of strings	Available protocols for routes using the domain, currently http and tcp
relationships.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
relationships.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
metadata.labels	label object	Labels applied to the domain
metadata.annotations	annotation object	Annotations applied to the domain
links	links object	Links to related resources

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,
  "router_group": null,
  "supported_protocols": ["http"],
  "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, or external (user-to-container) traffic	false
router_group.guid	uuid	The desired router group guid. note: creates a tcp domain; cannot be used when internal is set to true or domain is scoped to an org	null
organization	to-one relationship	A relationship to the organization the domain will be scoped to; note: cannot be used when internal is set to true or domain is associated with a router group
shared_organizations	to-many relationship	A relationship to organizations the domain will be shared with Note: cannot be used without an organization relationship
metadata.labels	label object	Labels applied to the domain
metadata.annotations	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,
  "router_group": null,
  "supported_protocols": ["http"],
  "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,
      "router_group": { "guid": "5806148f-cce6-4d86-7fbd-aa269e3f6f3f" },
      "supported_protocols": ["tcp"],
      "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"
        },
        "router_group": {
          "href": "https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f"
        }
      }
    },
  ]
}

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
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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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,
      "router_group": { "guid": "5806148f-cce6-4d86-7fbd-aa269e3f6f3f" },
      "supported_protocols": ["tcp"],
      "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"
        },
        "router_group": {
          "href": "https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f"
        }
      }
    },
  ]
}

Retrieve all domains available in an organization for the current user. This will return unscoped domains (those without an owning organization), domains that are scoped to the given organization (owned by the given organization), and domains that have been shared with the organization.

To retrieve the default domain for an organization, use the get default domain endpoint.

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
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	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,
  "router_group": null,
  "supported_protocols": ["http"],
  "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	label object	Labels applied to the domain
metadata.annotations	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"
      },
    "download": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the droplet
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
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
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
relationships.app	to-one relationship	The app the droplet belongs to
metadata.labels	labels object	Labels on the droplet
metadata.annotations	annotations object	Annotations on the droplet
links	links object	Links to related resources

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"
      },
    "download": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
    }
  },
  "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"
        },
        "download": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
        }
      },
      "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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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"
        },
        "download": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
        }
      },
      "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	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"
        },
        "download": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
        }
      },
      "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	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"
      },
      "download": {
        "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
      }
    },
    "metadata": {
      "labels": {
        "release": "stable"
      },
      "annotations": {
        "note": "detailed information"
      }
    }
  }

Definition

PATCH /v3/droplets/:guid

Optional parameters

Name	Type	Description
metadata.labels	label object	Labels applied to the droplet
metadata.annotations	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

Download droplet bits

Example Request

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

Example Response

HTTP/1.1 302 FOUND
Content-Type: application/json

Download a gzip compressed tarball file containing a Cloud Foundry compatible droplet. 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 relayed 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.

Only droplets that are in the STAGED state and have lifecycle type buildpack can be downloaded.

Definition

GET /v3/droplets/:guid/download

Permitted roles

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

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
updated_at	string	The time of last update
name	string	The name of the group; can only be running or staging
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	timestamp	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. The package upload endpoint will not cache any uploaded packages for resource matching.
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
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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.

Get platform usage summary

Example Request

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

Example Response

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

{
  "usage_summary": {
    "started_instances": 294,
    "memory_in_mb": 123945
  },
  "links": {
    "self": { "href": "http://api.example.com/v3/info/usage_summary" }
  }
}

This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation.

Definition

GET /v3/info/usage_summary

Usage summary object

Name	Type	Description
started_instances	integer	Total number of process instances in the STARTED state
memory_in_mb	integer	Sum of memory usage of all tasks in the RUNNING state and all process instances in the STARTED state

Permitted roles

Admin
Admin Read-Only
Global Auditor

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
guid	uuid	Unique identifier for the isolation segment
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
name	string	Name of the isolation segment
metadata.labels	labels object	Labels on the isolation segment
metadata.annotations	annotations object	Annotations on the isolation segment
links	links object	Links to related resources

Create an isolation segment

Example Request

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

Example Response

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

{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "name": "an_isolation_segment",
   "created_at": "2016-10-19T20:25:04Z",
   "updated_at": "2016-11-08T16:41:26Z",
   "links": {
      "self": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
      }
   },
   "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	label object	Labels applied to the isolation segment
metadata.annotations	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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	label object	Labels applied to the isolation segment
metadata.annotations	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": [],
  "warnings": []
}

Name	Type	Description
guid	uuid	Unique identifier for the job
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	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, POLLING, COMPLETE, orFAILED
errors	errors list	Array of errors that occurred while processing the job
warnings	warnings list	Array of warnings that occurred while processing the job
links	links object	Links to related resources

Note: POLLING happens during asynchronous services operations that require polling the last operation from the service broker.

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": [],
  "warnings": []
}

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"
    }
  ],
  "warnings": [
    {
      "detail": "warning! warning!"
    }
  ]
}

Definition

GET /v3/jobs/:guid

Permitted roles

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

Manifests

A manifest is a method for applying bulk configurations to apps and their underlying processes.

Manifests are in the YAML format. However, anchors and aliases are not supported.

The manifest schema

Example Manifest

---
version: 1
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
    binding_name: my-binding
    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

Name	Type	Description
applications	array of app configurations	Configurations for apps in the space
version	integer	The manifest schema version; currently the only valid version is 1, defaults to 1 if not provided

App-level configuration

This configuration is specified per application and applies to all of the application’s processes.

Name	Type	Description
name	string	Name of the app
buildpacks	list of strings	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	object	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	object	A key-value mapping of environment variables to be used for the app when running
no-route	boolean	When set to true, any routes specified with the routes attribute will be ignored and any existing routes will be removed
processes	array of process configurations	List of configurations for individual process types
random-route	boolean	Creates a random route for the app if true; if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored regardless of its value
default-route	boolean	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 routes is specified, if the app already has routes, or if no-route is specified, this field is ignored regardless of its value
routes	array of route objects	List declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist; example route object: - route: www.examplecom/path
services	array of service configurations	A list of service-instances to bind to the app
sidecars	array of sidecar configurations	A list of configurations for individual sidecars
stack	string	The root filesystem to use with the buildpack, for example cflinuxfs3
metadata.labels	label object	Labels applied to the app
metadata.annotations	annotation object	Annotations applied to the app
buildpack	string	DEPRECATED in favor of the buildpacks field above

Process-level configuration

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

For backwards compatibility, the web process configuration may be placed at the top level of the application configuration, rather than listed under processes. However, if there is a process with type: web listed under processes, this configuration will override any at the top level.

Name	Type	Description
type	string	(Required) The identifier for the processes to be configured
command	string	The command used to start the process; this overrides start commands from Procfiles and buildpacks
disk_quota	string	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	string	Endpoint called to determine if the app is healthy
health-check-invocation-timeout	integer	The timeout in seconds for individual health check requests for http and port health checks
health-check-type	string	Type of health check to perform; none is deprecated and an alias to process
instances	integer	The number of instances to run
memory	string	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	integer	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.

Name	Type	Description
name	string	(Required) The name of the service instance to be bound to
binding_name	string	The name of the service binding to be created
parameters	object	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.

Name	Type	Description
name	string	(Required) The identifier for the sidecars to be configured
command	string	The command used to start the sidecar
process_types	list of strings	List of processes to associate sidecar with
memory	integer	Memory in MB that the sidecar will be allocated

Apply a manifest to a space

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. The apps must reside in the space. 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

Generate a manifest for an app

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
  services:
  - my-service
  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

Create a manifest diff for a space (experimental)

Example Request

curl "https://api.example.org/v3/spaces/[guid]/manifest_diff" \
  -X POST \
  -H "Content-Type: application/x-yaml" \
  -H "Authorization: bearer [token]" \
  -d @/path/to/manifest.yml

Example Response

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

{
  "diff": [
    {
      "op": "remove",
      "path": "/applications/0/routes/1",
      "was": {"route": "route.example.com"}
    },
    {
      "op": "add",
      "path": "/applications/1/buildpacks/2",
      "value": "java_buildpack"
    },
    {
      "op": "replace",
      "path": "/applications/2/processes/1/memory",
      "was": "256M",
      "value": "512M"
    }
  ]
}

This endpoint returns a JSON representation of the difference between the provided manifest and the current state of a space.

Currently, this endpoint can only diff version 1 manifests.

The diff object

The diff object format is inspired by the JSON Patch specification.

Name	Type	Description
op	string	Type of change; valid values are add, remove, replace
path	string	Path to changing manifest field
was	any	For remove and replace operations, the previous value; otherwise key is omitted
value	any	For add and replace operations, the new value; otherwise key is omitted

Definition

POST /v3/spaces/:guid/manifest_diff

Permitted Roles

Admin
Space Developer

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
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
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
metadata.labels	label object	Labels applied to the organization
metadata.annotations	annotation object	Annotations added to the organization
links	links object	Links to related resources

Create an organization

Example Request

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

Example Response

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

{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "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	boolean	Whether an organization is suspended or not
metadata.labels	label object	Labels applied to the organization
metadata.annotations	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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	boolean	Whether an organization is suspended or not
metadata.labels	label object	Labels applied to the organization
metadata.annotations	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,
  "router_group": null,
  "supported_protocols": ["http"],
  "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	timestamp	The time with zone when the organization quota was created
updated_at	timestamp	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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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
guid	uuid	Unique identifier for the package
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
type	string	Package type; valid values are bits, docker
data	object	Data for package type (see below)
state	string	State of the package; valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, EXPIRED
relationships.app	to-one relationship	The app the package belongs to
metadata.labels	label object	Labels applied to the package
metadata.annotations	annotation object	Annotations applied to the package
links	links object	Links to related resources

Bits package data

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
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

Docker package data

A Docker package references a Docker image from a registry.

Name	Type	Description
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

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	label object	Labels applied to the package
metadata.annotations	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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	label object	Labels applied to the package
metadata.annotations	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
guid	uuid	Unique identifier for the process
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
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	to-one relationship	The app the process belongs to
relationships.revision (experimental)	to-one relationship	The app revision the process is currently running
metadata.labels	label object	Labels applied to the process
metadata.annotations	annotation object	Annotations applied to the process
links	links object	Links to related resources

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,
      "external_tls_proxy_port": 61002,
      "internal_tls_proxy_port": 61003
    }
  ],
  "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	timestamp	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 current maximum memory allocated for the instance
disk_quota	integer	The current maximum disk allocated for the instance
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,
          "external_tls_proxy_port": 61002,
          "internal_tls_proxy_port": 61003
        }
      ],
      "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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	label object	Labels applied to the process
metadata.annotations	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	timestamp	The time with zone when the role was created
updated_at	timestamp	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	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	Optionally include a list of unique related resources in the response; valid values are user, space, and organization
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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

Root

These endpoints link to other resources, endpoints, and external services that are relevant to API clients.

Global API Root

Example Request

curl "https://api.example.org"

Example Response

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

{
  "links": {
    "self": {
      "href": "https://api.example.org"
    },
    "bits_service": null,
    "cloud_controller_v2": {
      "href": "https://api.example.org/v2",
      "meta": {
        "version": "2.155.0"
      }
    },
    "cloud_controller_v3": {
      "href": "https://api.example.org/v3",
      "meta": {
        "version": "3.90.0"
      }
    },
    "network_policy_v0": {
      "href": "https://api.example.org/networking/v0/external"
    },
    "network_policy_v1": {
      "href": "https://api.example.org/networking/v1/external"
    },
    "login": {
      "href": "https://login.example.org"
    },
    "uaa": {
      "href": "https://uaa.example.org"
    },
    "credhub": null,
    "routing": {
      "href": "https://api.example.org/routing"
    },
    "logging": {
      "href": "wss://doppler.example.org:443"
    },
    "log_cache": {
      "href": "https://log-cache.example.org"
    },
    "log_stream": {
      "href": "https://log-stream.example.org"
    },
    "app_ssh": {
      "href": "ssh.example.org:2222",
      "meta": {
        "host_key_fingerprint": "Y411oivJwZCUQnXHq83mdM5SKCK4ftyoSXI31RRe4Zs",
        "oauth_client": "ssh-proxy"
      }
    }
  }
}

This endpoint returns links to the APIs available on a given Cloud Foundry deployment.

Definition

GET /

Authentication

No authentication required.

V3 API Root

Example Request

curl "https://api.example.org/v3"

Example Response

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

{
  "links": {
    "self": {
      "href": "https://api.example.org/v3"
    },
    "app_usage_events": {
      "href": "https://api.example.org/v3/app_usage_events"
    },
    "apps": {
      "href": "https://api.example.org/v3/apps"
    },
    "audit_events": {
      "href": "https://api.example.org/v3/audit_events"
    },
    "buildpacks": {
      "href": "https://api.example.org/v3/buildpacks"
    },
    "builds": {
      "href": "https://api.example.org/v3/builds"
    },
    "deployments": {
      "href": "https://api.example.org/v3/deployments"
    },
    "domains": {
      "href": "https://api.example.org/v3/domains"
    },
    "droplets": {
      "href": "https://api.example.org/v3/droplets"
    },
    "environment_variable_groups": {
      "href": "https://api.example.org/v3/environment_variable_groups"
    },
    "feature_flags": {
      "href": "https://api.example.org/v3/feature_flags"
    },
    "info": {
      "href": "https://api.example.org/v3/info"
    },
    "isolation_segments": {
      "href": "https://api.example.org/v3/isolation_segments"
    },
    "organizations": {
      "href": "https://api.example.org/v3/organizations"
    },
    "organization_quotas": {
      "href": "https://api.example.org/v3/organization_quotas"
    },
    "packages": {
      "href": "https://api.example.org/v3/packages"
    },
    "processes": {
      "href": "https://api.example.org/v3/processes"
    },
    "resource_matches": {
      "href": "https://api.example.org/v3/resource_matches"
    },
    "roles": {
      "href": "https://api.example.org/v3/roles"
    },
    "routes": {
      "href": "https://api.example.org/v3/routes"
    },
    "security_groups": {
      "href": "https://api.example.org/v3/security_groups"
    },
    "service_brokers": {
      "href": "https://api.example.org/v3/service_brokers"
    },
    "service_instances": {
      "href": "https://api.example.org/v3/service_instances",
      "experimental": true
    },
    "service_offerings": {
      "href": "https://api.example.org/v3/service_offerings"
    },
    "service_plans": {
      "href": "https://api.example.org/v3/service_plans"
    },
    "service_usage_events": {
      "href": "https://api.example.org/v3/service_usage_events"
    },
    "spaces": {
      "href": "https://api.example.org/v3/spaces"
    },
    "space_quotas": {
      "href": "https://api.example.org/v3/space_quotas"
    },
    "stacks": {
      "href": "https://api.example.org/v3/stacks"
    },
    "tasks": {
      "href": "https://api.example.org/v3/tasks"
    },
    "users": {
      "href": "https://api.example.org/v3/users"
    }
  }
}

This endpoint returns links to all the resources available on the v3 API.

Definition

GET /v3

Authentication

No authentication required.

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",
  "protocol": "tcp",
  "port": 6666,
  "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	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
protocol	string	The protocol supported by the route, based on the route’s domain configuration. Valid protocols are http and tcp
host	string	The hostname for the route; not compatible with routes specifying the tcp protocol; must be under 63 characters long and only contain letters, numbers, dashes (-) or underscores(_)
path	string	The path for the route; not compatible with routes specifying the tcp protocol; must be under 128 characters long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from RFC 2396
port	integer or null	The port that the route listens on. Only compatible with routes specifying the tcp protocol
url	string	The URL for the route; URLs of protocol http are a combination of host, domain name, and path; URLs of protocol tcp are a combination of domain name and port
destinations	array of destination objects	List of destinations for the route
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
metadata.labels	label object	Labels applied to the route
metadata.annotations	annotation object	Annotations applied to the route
links	links object	Links to related resources

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",
    "port": 6666,
    "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",
  "protocol": "tcp",
  "port": 6666,
  "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; not compatible with routes specifying the tcp protocol
path	string	The path component for the route; should begin with a / and not compatible with routes specifying the tcp protocol
port	integer	The port the route will listen on; only compatible with routes leveraging a domain that supports the tcp protocol. For tcp domains, a port will be randomly assigned if not specified
metadata.annotations	annotation object	Annotations applied to the route
metadata.labels	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",
  "protocol": "tcp",
  "port": 6666,
  "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	Optionally include additional related resources in the response Valid values are domain, space.organization, space

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",
      "protocol": "http",
      "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
app_guids	list of strings	Comma-delimited list of app guids to filter by
domain_guids	list of strings	Comma-delimited list of domain guids to filter by
hosts	list of strings	Comma-delimited list of hostnames to filter by
organization_guids	list of strings	Comma-delimited list of organization guids to filter by
paths	list of strings	Comma-delimited list of paths to filter by (e.g. /path1,/path2)
ports	list of integers	Comma-delimited list of ports to filter by (e.g. 3306,5432)
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
label_selector	string	A query string containing a list of label selector requirements
include	string	Optionally include a list of unique related resources in the response Valid values are domain, space.organization, space
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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",
      "protocol": "http",
      "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
domain_guids	list of strings	Comma-delimited list of domain guids to filter by
hosts	list of strings	Comma-delimited list of hostnames to filter by
organization_guids	list of strings	Comma-delimited list of organization guids to filter by
paths	list of strings	Comma-delimited list of paths to filter by (e.g. /path1,/path2)
ports	list of integers	Comma-delimited list of ports to filter by (e.g. 3306,5432)
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
label_selector	string	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",
  "protocol": "tcp",
  "port": 6666,
  "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	label object	Labels applied to the route
metadata.annotations	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 and only applicable to http routes
path	string	Path to filter by; defaults to empty string if not provided and only applicable to http routes
port	integer	Port to filter by; only applicable to tcp routes and required for tcp routes

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]"
  -H "Content-type: application/json"
  -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.

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
guid	uuid	Unique identifier for the security group
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
name	string	Name of the security group
rules	array of rule objects	Rules that will be applied by this 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
relationships.running_spaces	to-many relationship	A relationship to the spaces where the security_group is applied to applications during runtime
relationships.staging_spaces	to-many relationship	A relationship to the spaces where the security_group is applied to applications during staging
links	links object	Links to related resources

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), where -1 allows all	no	null
code	integer	Code required for ICMP protocol; valid values are between -1 and 255 (inclusive), where -1 allows all	no	null
description	string	A description for the rule; this field is limited to 16MB	no	null
log	boolean	Enable logging for rule, only valid for tcp rules	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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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

Update a security group

Example Request

curl "https://api.example.org/v3/security_groups/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
  "name": "my-group0",
  "globally_enabled": {
    "running": true
  }
  "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 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"
    }
  }
}

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

Updates to the rules parameter will fully replace the current set of rules for the security group.

Updates to the globally_enabled parameter will be merged with the existing configuration. For example, an update to the globally_enabled.running parameter will not affect the globally_enabled.staging configuration.

Definition

PATCH /v3/security_groups/:guid

Optional parameters

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

Permitted roles

Admin

Delete a security group

Example Request

curl "https://api.example.org/v3/security_groups/[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/security_groups/:guid

Permitted roles

Admin

Bind a running security group to spaces

Example Request

curl "https://api.example.org/v3/security_groups/[guid]/relationships/running_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 200 OK
Content-Type: application/json

{
  "data": [
    { "guid": "space-guid1" },
    { "guid": "space-guid2" },
    { "guid": "previous-space-guid" }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a/relationships/running_spaces"
    }
  }
}

This endpoint binds one or more spaces to a security group with the running lifecycle.

Running app containers within these spaces will inherit the rules specified by this security group.

Apps within these spaces must be restarted for these changes to take effect.

Unless a security group is globally-enabled, an admin must add it to a space for it to be visible for the org and space managers. Once it’s visible, org and space managers can add it to additional spaces.

Definition

POST /v3/security_groups/:guid/relationships/running_spaces

Required parameters

Name	Type	Description
data	to-many relationship	Space guids that will be bound to the security group

Permitted roles

Role	Notes
Admin
Space Manager	Can bind visible security groups to their spaces (visible groups are globally–enabled security groups or groups associated with a space they can see)
Org Manager	Can bind visible security groups to their organizations’ spaces (visible groups are globally–enabled security groups or groups associated with a space they can see)

Bind a staging security group to spaces

Example Request

curl "https://api.example.org/v3/security_groups/[guid]/relationships/staging_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 200 OK
Content-Type: application/json

{
  "data": [
    { "guid": "space-guid1" },
    { "guid": "space-guid2" },
    { "guid": "previous-space-guid" }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a/relationships/staging_spaces"
    }
  }
}

This endpoint binds one or more spaces to a security group with the staging lifecycle.

Staging app containers within these spaces will inherit the rules specified by this security group.

Apps within these spaces must be restaged for these changes to take effect.

Unless a security group is globally-enabled, an admin must add it to a space for it to be visible for the org and space managers. Once it’s visible, org and space managers can add it to additional spaces.

Definition

POST /v3/security_groups/:guid/relationships/staging_spaces

Required parameters

Name	Type	Description
data	to-many relationship	Space guids that will be bound to the security group

Permitted roles

Role	Notes
Admin
Space Manager	Can bind visible security groups to their spaces (visible groups are globally–enabled security groups or groups associated with a space they can see)
Org Manager	Can bind visible security groups to their organizations’ spaces (visible groups are globally–enabled security groups or groups associated with a space they can see)

Unbind a running security group from a space

Example Request

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

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json

This endpoint removes a space from a security group with the running lifecycle.

Apps within this space must be restarted for these changes to take effect.

Definition

DELETE /v3/security_groups/:guid/relationships/running_spaces/:space_guid

Permitted roles

Role	Notes
Admin
Space Manager	Can unbind visible security groups from their spaces (visible groups are globally–enabled security groups or groups associated with a space they can see)
Org Manager	Can unbind visible security groups from their organizations’ spaces (visible groups are globally–enabled security groups or groups associated with a space they can see)

Unbind a staging security group from a space

Example Request

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

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json

This endpoint removes a space from a security group with the staging lifecycle.

Apps within this space must be restaged for these changes to take effect.

Definition

DELETE /v3/security_groups/:guid/relationships/staging_spaces/:space_guid

Permitted roles

Role	Notes
Admin
Space Manager	Can unbind visible security groups from their spaces (visible groups are globally–enabled security groups or groups associated with a space they can see)
Org Manager	Can unbind visible security groups from their organizations’ spaces (visible groups are 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": []
        },
        "running_spaces": {
          "data": [
            { "guid": "space-guid-1" },
            { "guid": "space-guid-2" }
          ]
        }
      },
      "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"
        }
      }
    }
  ]
}

This endpoint returns security groups that are enabled for running globally or at the space level for the given space.

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

List staging security groups for a space

Example Request

curl "https://api.example.org/v3/spaces/[guid]/staging_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/staging_security_groups?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/staging_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": false,
        "staging": true
      },
      "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"
        }
      }
    }
  ]
}

This endpoint returns security groups that are enabled for staging globally or at the space level for the given space.

Definition

GET /v3/spaces/:guid/staging_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 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",
  "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
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
name	string	Name of the service broker
url	string	URL of the service broker
relationships.space	to-one relationship	The space the service broker is restricted to; omitted for globally available service brokers
metadata.labels	label object	Labels applied to the service broker
metadata.annotations	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. See Service broker jobs for more information and limitations.

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	label object	Labels applied to the service broker
metadata.annotations	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",
  "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",
      "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",
      "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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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 with job

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

Example Response without job

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

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "name": "my_service_broker",
  "url": "https://example.service-broker.com",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "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 updates a service broker. Depending on the parameters specified, the endpoint may respond with a background job, and it may synchronize the service offerings and service plans with those in the broker’s catalog.

When a service broker has a synchronization job in progress, only updates with metadata are permitted until the synchronization job is complete.

Parameter	Updates Catalog	Responds with job
name	No	Yes
url	Yes	Yes
authentication	Yes	Yes
metadata.labels	No	No
metadata.annotations	No	No

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	label object	Labels applied to the service broker
metadata.annotations	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. See Service broker jobs for more information and limitations.

Definition

DELETE /v3/service_brokers/:guid

Permitted roles

Admin
Space Developer (only space-scoped brokers)

Service broker jobs

CRUD operations for service brokers are asynchronous. create, update and delete endpoints include a job URL in the Location header of the HTTP response.

These jobs are the only source of information about the progress of the operation. Therefore, the job must be polled to find out when the process ends and if it was successful. There is no mechanism to link a service broker with its jobs, apart from the Location header in the API response.

When a failure occurs during a create job, the service broker won’t be usable. It will still be included in the GET endpoints responses, hence the importance of querying the job to find out the end status.

When updating a service broker, catalog changes will be rolled-back in the event of the job failing. The service broker catalog will remain unchanged with no indication that the update operation failed. Querying the job will provide such information.

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,
  "documentation_url": "https://some-documentation-link.io",
  "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": {
        "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
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
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
shareable	boolean	Whether or not service Instances of this service offering can be shared across organizations and spaces
documentation_url	string	Url that points to a documentation page for the service offering, if provided by the service broker as part of the metadata field
broker_catalog	broker catalog object	This object contains information obtained from the service broker Catalog
relationships.service_broker	to-one relationship	The service broker that provides this service offering
metadata.labels	label object	Labels applied to the service offering
metadata.annotations	annotation object	Annotations added to the service offering
links	links object	Links to related resources

The service offering broker catalog

Name	Type	Description
id	string	The identifier that the service broker provided for this service offering
metadata	object	Additional information provided by the service broker as specified by OSBAPI
features.plan_updateable	boolean	Whether the service offering supports upgrade/downgrade for service plans by default; service plans can override this field
features.bindable	boolean	Specifies whether service Instances of the service can be bound to applications
features.instances_retrievable	boolean	Specifies whether the Fetching a service instance endpoint is supported for all service plans
features.bindings_retrievable	boolean	Specifies whether the Fetching a service binding endpoint is supported for all service plans
features.allow_context_updates	boolean	Specifies whether service instance updates relating only to context are propagated to the service broker

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,
  "documentation_url": "https://some-documentation-link.io",
  "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": {
        "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

Query parameters

Name	Type	Description
fields	fields parameter	Allowed values

Service Offering Fields

Resource	Allowed Keys
service_broker	guid, name

Permitted roles

All Roles
Unauthenticated Users (for service offerings with public plans, unless hide_marketplace_from_unauthenticated_users is set)

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,
      "documentation_url": "https://some-documentation-link.io",
      "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": {
            "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,
      "documentation_url": "https://some-other-documentation-link.io",
      "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": {
            "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	A query string containing a list of label selector requirements
fields (experimental)	fields parameter	Allowed values
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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

Service Offerings List Fields

Resource	Allowed Keys
service_broker	guid, name

Permitted roles

All Roles
Unauthenticated Users (for service offerings with public plans, unless hide_marketplace_from_unauthenticated_users is set)

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,
  "documentation_url": "https://some-documentation-link.io",
  "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": {
        "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	label object	Labels applied to the service offering
metadata.annotations	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,
  "costs": [
    {
      "currency": "USD",
      "amount": 199.99,
      "unit": "Monthly"
    }
  ],
  "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": {
        "parameters": {}
      }
    },
    "service_binding": {
      "create": {
        "parameters": {}
      }
    }
  },
  "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
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
name	string	Name of the service plan
visibility_type	string	Denotes the visibility of the plan; can be public, admin, organization, space, see list of visibility types
available	boolean	Whether or not the service plan is available
free	boolean	Whether or not the service plan is free of charge
costs	array of cost objects	The cost of the service plan as obtained from the service broker catalog
description	string	Description of the service plan
maintenance_info	maintenance_info object	Information about the version of this service plan
broker_catalog	broker catalog object	This object contains information obtained from the service broker catalog
schemas	schemas object	Schema definitions for service instances and service bindings for the service plan
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	label object	Labels applied to the service plan
metadata.annotations	annotation object	Annotations added to the service plan
links	links object	Links to related resources

The service plan cost

Name	Type	Description
amount	float	Pricing amount
currency	string	Currency code for the pricing amount, e.g. USD, GBP
unit	string	Display name for type of cost, e.g. Monthly, Hourly, Request, GB

The maintenance info object for service plans

Name	Type	Description
version	string	The current semantic version of the service plan; comparing this version with that of a service instance can be used to determine whether or not the service instance is up to date with this service plan
description	string	A textual explanation associated with this version

The service plan broker catalog

Name	Type	Description
id	string	The identifier that the service broker provided for this service plan
metadata	object	Additional information provided by the service broker as specified by OSBAPI
maximum_polling_duration	integer	The maximum number of seconds that Cloud Foundry will wait for an asynchronous service broker operation
features.plan_updateable	boolean	Whether the service plan supports upgrade/downgrade for service plans; when the catalog does not specify a value, it is inherited from the service offering
features.bindable	boolean	Specifies whether service instances of the service can be bound to applications

The service plan schemas

Name	Type	Description
service_instance.create	object	Schema definition for service instance creation
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
service_instance.update	object	Schema definition for service instance update
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
service_binding.create	object	Schema definition for service Binding creation
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

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,
  "costs": [
    {
      "currency": "USD",
      "amount": 199.99,
      "unit": "Monthly"
    }
  ],
  "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": {
        "parameters": {}
      }
    },
    "service_binding": {
      "create": {
        "parameters": {}
      }
    }
  },
  "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

Query parameters

Name	Type	Description
fields	fields parameter	Allowed values
include	list of strings	Optionally include a list of related resources in the response; valid values are space.organization and service_offering

Service Plan Fields

Resource	Allowed Keys
service_offering.service_broker	guid, name

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,
      "costs": [
        {
          "currency": "USD",
          "amount": 199.99,
          "unit": "Monthly"
        }
      ],
      "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": {
            "parameters": {}
          }
        },
        "service_binding": {
          "create": {
            "parameters": {}
          }
        }
      },
      "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": true,
      "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": {
            "parameters": {}
          },
          "update": {
            "parameters": {}
          }
        },
        "service_binding": {
          "create": {
            "parameters": {}
          }
        }
      },
      "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_ids	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
include	list of strings	Optionally include a list of unique related resources in the response; valid values are space.organization and service_offering
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	A query string containing a list of label selector requirements
fields (experimental)	fields parameter	Allowed values
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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.

Service plans list fields

Resource	Allowed keys
service_offering.service_broker	guid, name

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,
  "costs": [
    {
      "currency": "USD",
      "amount": 199.99,
      "unit": "Monthly"
    }
  ],
  "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": {
        "parameters": {}
      }
    },
    "service_binding": {
      "create": {
        "parameters": {}
      }
    }
  },
  "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	label object	Labels applied to the service plan
metadata.annotations	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 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"
}

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

Service Instances

An instantiation of a service.

Service instances can be of type managed when it is an instantiation of a service offering registered with CF or user-provided when it describes an instance of an offering that is not registered with CF.

The service instance object

Example Managed Service Instance object

{
  "guid": "c89b3280-fe8d-4aa0-a42e-44465bb1c61c",
  "created_at": "2020-03-10T15:49:29Z",
  "updated_at": "2020-03-10T15:49:29Z",
  "name": "my-managed-instance",
  "tags": [],
  "type": "managed",
  "maintenance_info": {
    "version": "1.0.0"
  },
  "upgrade_available": false,
  "dashboard_url": "https://service-broker.example.org/dashboard",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "relationships": {
    "service_plan": {
      "data": {
        "guid": "5358d122-638e-11ea-afca-bf6e756684ac"
      }
    },
    "space": {
      "data": {
        "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    },
    "service_plan": {
      "href": "https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters"
    },
    "shared_spaces": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces"
    },
    "service_credential_bindings": {
      "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    },
    "service_route_bindings": {
      "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    }
  }
}

Example User-Provided Service Instance object

{
  "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
  "created_at": "2020-03-10T15:56:08Z",
  "updated_at": "2020-03-10T15:56:08Z",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "name": "my-user-provided-instance",
  "tags": ["sql"],
  "type": "user-provided",
  "syslog_drain_url": "http://logs.com",
  "route_service_url": "https://routes.com",
  "relationships": {
    "space": {
      "data": {
        "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
    },
    "credentials": {
      "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
    },
    "service_credential_bindings": {
      "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
    },
    "service_route_bindings": {
      "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the service instance
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
name	string	Name of the service instance
type	string	Either managed or user-provided
tags	list of strings	Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env
syslog_drain_url	string	URL to which logs for bound applications will be streamed; only shown when type is user-provided
route_service_url	string	URL to which requests for bound routes will be forwarded; only shown when type is user-provided
maintenance_info	maintenance_info object	Information about the version of this service instance; only shown when type is managed
upgrade_available	bool	Whether or not an upgrade of this service instance is available on the current Service Plan; details are available in the maintenance_info object; Only shown when type is managed
dashboard_url	string	The URL to the service instance dashboard (or null if there is none); only shown when type is managed
last_operation	last operation object	The last operation of this service instance
relationships.service_plan	to-one relationship	The service plan the service instance relates to; only shown when type is managed
relationships.space	to-one relationship	The space the service instance is contained in
metadata.labels	label object	Labels applied to the service instance
metadata.annotations	annotation object	Annotations applied to the service instance
links	links object	Links to related resources

The maintenance info object for service instances

Name	Type	Description
version	string	The current semantic version of this service instance; comparing this version with the version of the Service Plan can be used to determine whether or not this service instance is up to date with the Service Plan
description	string	A textual explanation associated with this version

The last operation object for service instances

Name	Type	Description
type	string	Either create, update, or delete
state	string	Either in progress, succeeded, or failed
description	string	A textual explanation associated with this state
created_at	timestamp	The time with zone when the operation started
updated_at	timestamp	The time with zone when the operation was last updated

Create a service instance

Example Request for Managed Service Instance

curl "https://api.example.org/v3/service_instances" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "managed",
    "name": "my_service_instance",
    "parameters": {
      "foo": "bar",
      "baz": "qux"
    },
    "tags": ["foo", "bar", "baz"],
    "metadata": {
      "annotations": {
        "foo": "bar"
      },
      "labels": {
        "baz": "qux"
      }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
        }
      },
      "service_plan": {
        "data": {
          "guid": "e0e4417c-74ee-11ea-a604-48bf6bec2d78"
        }
      }
    }
  }'

Example Response for Managed Service Instance

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

Example Request for User-Provided Service Instance

curl "https://api.example.org/v3/service_instances" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "user-provided",
    "name": "my_service_instance",
    "credentials": {
      "foo": "bar",
      "baz": "qux"
    },
    "tags": ["foo", "bar", "baz"],
    "syslog_drain_url": "https://syslog.com/drain",
    "route_service_url": "https://route.com/service",
    "metadata": {
      "annotations": {
        "foo": "bar"
      },
      "labels": {
        "baz": "qux"
      }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
        }
      }
    }
  }'

Example Response for User-Provided Service Instance

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

{
  "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
  "created_at": "2020-03-10T15:56:08Z",
  "updated_at": "2020-03-10T15:56:08Z",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "name": "my-user-provided-instance",
  "tags": ["sql"],
  "type": "user-provided",
  "syslog_drain_url": "http://logs.com",
  "route_service_url": "https://routes.com",
  "relationships": {
    "space": {
      "data": {
        "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
      }
    }
  },
  "metadata": {
    "labels": {"baz": "qux"},
    "annotations": {"foo": "bar"}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
    },
    "credentials": {
      "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
    },
    "service_credential_bindings": {
      "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
    },
    "service_route_bindings": {
      "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
    }
  }
}

This endpoint creates a new service instance. Service instances can be of type managed or user-provided, and the required parameters are different for each type. User provided service instances do not require interactions with service brokers.

If failures occur when creating managed service instances, the API might execute orphan mitigation steps accordingly to cases outlined in the OSBAPI specification

Definition

POST /v3/service_instances

Required parameters for managed service instance

Name	Type	Description
type	string	Must be managed
name	string	Name of the service instance
relationships.space	to-one relationship	The space in which to create the service instance
relationships.service_plan	to-one relationship	The service plan from which to create the service instance

Optional parameters for managed service instance

Name	Type	Description
tags	list of strings	Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env
parameters	object	A JSON object that is passed to the service broker
metadata.labels	label object	Labels applied to the service instance
metadata.annotations	annotation object	Annotations applied to the service instance

Required parameters for user-provided service instance

Name	Type	Description
type	string	Must be user-provided
name	string	Name of the service instance
relationships.space	to-one relationship	The space in which to create the service instance

Optional parameters for user-provided service instance

Name	Type	Description
tags	list of strings	Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env
credentials	object	A JSON object that is made available to apps bound to this service instance
syslog_drain_url	string	URL to which logs for bound applications will be streamed
route_service_url	string	URL to which requests for bound routes will be forwarded; must use the https protocol
metadata.labels	label object	Labels applied to the service instance
metadata.annotations	annotation object	Annotations applied to the service instance

Permitted roles

Admin
Space Developer

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": 2,
    "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": "c89b3280-fe8d-4aa0-a42e-44465bb1c61c",
      "created_at": "2020-03-10T15:49:29Z",
      "updated_at": "2020-03-10T15:49:29Z",
      "name": "my-managed-instance",
      "tags": [],
      "type": "managed",
      "maintenance_info": {
        "version": "1.0.0"
      },
      "upgrade_available": false,
      "dashboard_url": "https://service-broker.example.org/dashboard",
      "last_operation": {
        "type": "create",
        "state": "succeeded",
        "description": "Operation succeeded",
        "updated_at": "2020-03-10T15:49:32Z",
        "created_at": "2020-03-10T15:49:29Z"
      },
      "relationships": {
        "service_plan": {
          "data": {
            "guid": "5358d122-638e-11ea-afca-bf6e756684ac"
          }
        },
        "space": {
          "data": {
            "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
        },
        "service_plan": {
          "href": "https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
        },
        "parameters": {
          "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters"
        },
        "shared_spaces": {
          "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces"
        },
        "service_credential_bindings": {
          "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
        },
        "service_route_bindings": {
          "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
        }
      }
    },
    {
      "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
      "created_at": "2020-03-10T15:56:08Z",
      "updated_at": "2020-03-10T15:56:08Z",
      "name": "my-user-provided-instance",
      "tags": ["sql"],
      "type": "user-provided",
      "syslog_drain_url": "http://logs.com",
      "route_service_url": "https://routes.com",
      "last_operation": {
        "type": "update",
        "state": "succeeded",
        "description": "Operation succeeded",
        "updated_at": "2020-03-10T15:59:32Z",
        "created_at": "2020-03-10T15:59:29Z"
      },
      "relationships": {
        "space": {
          "data": {
           "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
        },
        "credentials": {
          "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
        },
        "service_credential_bindings": {
          "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
        },
        "service_route_bindings": {
          "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
        }
      }
    }
  ]
}

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
type	string	Filter by type; valid values are managed and user-provided
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_plan_guids	list of strings	Comma-delimited list of service plan guids to filter by
service_plan_names	list of strings	Comma-delimited list of service plan names to filter by
page	integer	Page to display; valid values are integers >= 1
per_page	integer	Number of results per page; valid values are 1 through 5000
order_by	string	Value to sort by. Defaults to ascending; prepend with - to sort descending Valid values are created_at, updated_at, and name
label_selector	string	A query string containing a list of label selector requirements
fields	fields parameter	Allowed values
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

Service Instances List Fields

Resource	Allowed Keys
space	guid, name, relationships.organization
space.organization	guid, name
service_plan	guid, name, relationships.service_offering
service_plan.service_offering	guid, name, description, documentation_url, tags, relationships.service_broker
service_plan.service_offering.service_broker	guid, name

Permitted roles

All Roles

Get a service instance

Example Request

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

Example Managed Service Instance Response

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

{
  "guid": "c89b3280-fe8d-4aa0-a42e-44465bb1c61c",
  "created_at": "2020-03-10T15:49:29Z",
  "updated_at": "2020-03-10T15:49:29Z",
  "name": "my-managed-instance",
  "tags": [],
  "type": "managed",
  "maintenance_info": {
    "version": "1.0.0"
  },
  "upgrade_available": false,
  "dashboard_url": "https://service-broker.example.org/dashboard",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "relationships": {
    "service_plan": {
      "data": {
        "guid": "5358d122-638e-11ea-afca-bf6e756684ac"
      }
    },
    "space": {
      "data": {
        "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    },
    "service_plan": {
      "href": "https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters"
    },
    "shared_spaces": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces"
    },
    "service_credential_bindings": {
      "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    },
    "service_route_bindings": {
      "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    }
  }
}

Example User-Provided Service Instance Response

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

{
  "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
  "created_at": "2020-03-10T15:56:08Z",
  "updated_at": "2020-03-10T15:56:08Z",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "name": "my-user-provided-instance",
  "tags": ["sql"],
  "type": "user-provided",
  "syslog_drain_url": "http://logs.com",
  "route_service_url": "https://routes.com",
  "relationships": {
    "space": {
      "data": {
        "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
    },
    "credentials": {
      "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
    },
    "service_credential_bindings": {
      "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
    },
    "service_route_bindings": {
      "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
    }
  }
}

This endpoint retrieves the service instance by GUID.

Definition

GET /v3/service_instances/:guid

Query parameters

Name	Type	Description
fields	fields parameter	Allowed values

Service Instance Fields

Resource	Allowed Keys
space	guid, name
space.organization	name, guid
service_plan	name, guid
service_plan.service_offering	name, guid, description, documentation_url, tags
service_plan.service_offering.service_broker	name, guid

Permitted roles

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

Get credentials for a user-provided service instance

Example Request

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

Example Response

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

{
  "username": "my-username",
  "password": "super-secret",
  "other": "credential"
}

Retrieves the credentials for a user-provided service instance. This endpoint is not available for managed service instances.

Definition

GET /v3/service_instances/:guid/credentials

Permitted roles

Admin
Admin Read-Only
Space Developer
Space Manager

Get parameters for a managed service instance

Example Request

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

Example Response

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

{
  "key_1": "value_1",
  "key_2": "value_2"
}

Queries the Service Broker for the parameters associated with this service instance. The broker catalog must have enabled the instances_retrievable feature for the Service Offering. Check the Service Offering object for the value of this feature flag.

Definition

GET /v3/service_instances/:guid/parameters

Permitted roles

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

Update a service instance

Example Request for Managed Service Instance

curl "https://api.example.org/v3/service_instances/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_service_instance",
    "parameters": {
      "foo": "bar",
      "baz": "qux"
    },
    "tags": ["foo", "bar", "baz"],
    "relationships": {
      "service_plan": {
        "data": {
          "guid": "f2b6ba9c-a4d2-11ea-8ae6-48bf6bec2d78"
        }
      }
    },
    "metadata": {
      "annotations": {
        "note": "detailed information"
      },
      "labels": {
        "key": "value"
      }
    }
  }'

(Experimental) Example Request for Managed Service Instance Upgrade (maintenance_info update)

curl "https://api.example.org/v3/service_instances/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "maintenance_info": {
      "version": "2.1.1"
    }
  }'

Example Synchronous Response for Managed Service Instance:

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

{
  "guid": "c89b3280-fe8d-4aa0-a42e-44465bb1c61c",
  "created_at": "2020-03-10T15:49:29Z",
  "updated_at": "2020-03-10T15:49:29Z",
  "name": "my-managed-instance",
  "tags": [],
  "type": "managed",
  "maintenance_info": {
    "version": "1.0.0"
  },
  "upgrade_available": false,
  "dashboard_url": "https://service-broker.example.org/dashboard",
  "last_operation": {
    "type": "update",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "relationships": {
    "service_plan": {
      "data": {
        "guid": "5358d122-638e-11ea-afca-bf6e756684ac"
      }
    },
    "space": {
      "data": {
        "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
      }
    }
  },
  "metadata": {
    "labels": {"key": "value"},
    "annotations": {"note": "detailed information"}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    },
    "service_plan": {
      "href": "https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters"
    },
    "shared_spaces": {
      "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces"
    },
    "service_credential_bindings": {
      "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    },
    "service_route_bindings": {
      "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
    }
  }
}

Example Asynchronous Response for Managed Service Instance:

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

(Experimental) Example Request for User-Provided Service Instance

curl "https://api.example.org/v3/service_instances/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_service_instance",
    "credentials": {
      "foo": "bar",
      "baz": "qux"
    },
    "tags": ["foo", "bar", "baz"],
    "syslog_drain_url": "https://syslog.com/drain",
    "route_service_url": "https://route.com/service",
    "metadata": {
      "annotations": {
        "foo": "bar"
      },
      "labels": {
        "baz": "qux"
      }
    }
  }'

(Experimental) Example Response for User-Provided Service Instance

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

{
  "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
  "created_at": "2020-03-10T15:56:08Z",
  "updated_at": "2020-03-10T15:56:08Z",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "name": "my-user-provided-instance",
  "tags": ["sql"],
  "type": "user-provided",
  "syslog_drain_url": "http://logs.com",
  "route_service_url": "https://routes.com",
  "relationships": {
    "space": {
      "data": {
        "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
      }
    }
  },
  "metadata": {
    "labels": {"baz": "qux"},
    "annotations": {"foo": "bar"}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
    },
    "credentials": {
      "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
    },
    "service_credential_bindings": {
      "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
    },
    "service_route_bindings": {
      "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
    }
  }
}

Definition

PATCH /v3/service_instances/:guid

Optional parameters for managed service instances

Name	Type	Description
name	string	Name of the service instance
tags	list of strings	Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env
parameters	object	A JSON object that is passed to the service broker
relationships.service_plan	to-one relationship	The service plan from which to create the service instance
maintenance_info	maintenance_info object	If provided, must have the version field; version must be a semantic version value and it must match the version in the maintenance_info for the service instance plan in the updated broker catalog. Any other value for version will cause a MaintenanceInfoConflict error
metadata.labels	label object	Labels applied to the service_instance
metadata.annotations	annotation object	Annotations applied to the service_instance

Some updates can be performed entirely within the Cloud Controller in which case the response is synchronous. Some updates require communication with the service broker, in which case the response will be asynchronous. The response will be asynchronous if any of these parameters are specified:

• parameters
• service_plan
• maintenance_info
• name - when the service offering has allow_context_updates feature enabled

Otherwise the response will be synchronous.

Optional parameters for user-provided service instances

Name	Type	Description
name	string	Name of the service instance
tags	list of strings	Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env
credentials	object	A JSON object that is made available to apps bound to this service instance
syslog_drain_url	string	URL to which logs for bound applications will be streamed
route_service_url	string	URL to which requests for bound routes will be forwarded; must use the https protocol
metadata.labels	label object	Labels applied to the service_instance
metadata.annotations	annotation object	Annotations applied to the service_instance

Permitted roles

Admin
Space Developer

Delete a service instance

Example Request

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

Example Response for User-provided Service Instances

HTTP/1.1 204 No Content

Example Response for Managed Service Instance

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint deletes a service instance and any associated service credential bindings or service route bindings. The service instance is removed from all spaces where it is available.

User provided service instances do not require interactions with service brokers, therefore the API will respond synchronously to the delete request.

For managed service instances, the API will respond asynchronously. If a service credential binding or service route binding cannot be deleted synchronously, then the operation will fail, and the deletion of the binding will continue in the background. The operation can be retried until it is successful.

Definition

DELETE /v3/service_instances/:guid

Query parameters

Name	Type	Description
purge	boolean	If true, deletes the service instance and all associated resources without any interaction with the service broker.

Permitted Roles

Admin
Space Developer

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

Query parameters

Name	Type	Description
fields	fields parameter	Allowed values

Shared Spaces List Fields

Resource	Allowed Keys
space	guid, name, relationships.organization
space.organization	guid, name

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

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

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 from the specified space. This will automatically unbind any applications bound to this service instance in the specified space. Unsharing a service instance from a space will not delete any service keys.

Definition

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

Permitted roles

Admin
Space Developer

Get usage summary in shared spaces

Example Request

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

Example Response

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

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

This endpoint returns the number of bound apps in spaces where the service instance has been shared to.

Definition

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

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

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

Service Credential Binding

Service credential bindings are used to make the details of the connection to a service instance available to an app or a developer.

Service credential bindings can be of type app or key.

A service credential binding is of type app when it is a binding between a service instance and an application Not all services support this binding, as some services deliver value to users directly without integration with an application. Field broker_catalog.features.bindable from service plan of the service instance can be used to determine if it is bindable.

A service credential binding is of type key when it only retrieves the details of the service instance and makes them available to the developer.

The service credential binding object

Example App Service Credential Binding object

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "name": "some-name",
  "type": "app",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "created_at": "2015-11-13T17:02:56Z",
    "updated_at": "2016-06-08T16:41:26Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
      }
    },
    "service_instance": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "details": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
    },
    "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"
    }
  }
}

Example Key Service Credential Binding object

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "name": "some-name",
  "type": "key",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "created_at": "2015-11-13T17:02:56Z",
    "updated_at": "2016-06-08T16:41:26Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "service_instance": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "details": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the service credential binding
name	string	Name of the binding. null when it’s not defined.
type	string	Either app or key
last_operation (experimental)	last operation object	The last operation of this binding
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
metadata.labels	label object	Labels applied to the service credential binding
metadata.annotations	annotation object	Annotations applied to the service credential binding
relationships.service_instance	to-one relationship	The service instance that this binding is originated from
relationships.app	to-one relationship	The app using this binding; omitted for key bindings
links	links object	Links to related resources

The last operation object for service credential binding

Name	Type	Description
type	string	Either create or delete
state	string	Either in progress, succeeded, or failed
description	string	A textual explanation associated with this state
created_at	timestamp	The time with zone when the operation started
updated_at	timestamp	The time with zone when the operation was last updated

Create a service credential binding

Example Request to create an App Credential Binding

curl "https://api.example.org/v3/service_credential_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "app",
    "name": "some-binding-name",
    "relationships": {
      "service_instance": {
        "data": {
          "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
        }
      },
      "app": {
        "data": {
          "guid": "e0e4417c-74ee-11ea-a604-48bf6bec2d78"
        }
      }
    },
    "parameters": {
      "key1": "value1",
      "key2": "value2"
    },
    "metadata": {
      "labels": {
        "foo": "bar"
      },
      "annotations": {
        "baz": "qux"
      }
    }
  }'

Example Request to create a Key Credential Binding

curl "https://api.example.org/v3/service_credential_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "key",
    "name": "some-binding-name",
    "relationships": {
      "service_instance": {
        "data": {
          "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
        }
      }
    },
    "parameters": {
      "key1": "value1",
      "key2": "value2"
    },
    "metadata": {
      "labels": {
        "foo": "bar"
      },
      "annotations": {
        "baz": "qux"
      }
    }
  }'

Example Response for a Managed Service Instance

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

Example Response for a User-Provided Service Instance

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

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "name": "some-name",
  "type": "app",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "created_at": "2015-11-13T17:02:56Z",
    "updated_at": "2016-06-08T16:41:26Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
      }
    },
    "service_instance": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "details": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

This endpoint creates a new service credential binding. Service credential bindings can be of type app or key; key is only valid for managed service instances.

If failures occur when creating a service credential binding for a managed service instances, the API might execute orphan mitigation steps accordingly to cases outlined in the OSBAPI specification

Definition

POST /v3/service_credential_bindings

Required parameters

Name	Type	Description
type	string	Type of the service credential binding. Valid values are key and app
relationships.service_instance	to-one relationship	The service instance to be bound
name	string	Name of the service credential binding. name is optional when the type is app

Optional parameters

Name	Type	Description
relationships.app	to-one relationship	The app to be bound. Required when type is app
parameters	object	A JSON object that is passed to the service broker
metadata.labels	label object	Labels applied to the service credential binding
metadata.annotations	annotation object	Annotations applied to the service credential binding

Permitted roles

Admin
Space Developer

Get a service credential binding

Example Request

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

Example App Credential Binding Response

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

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "name": "some-name",
  "type": "app",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "created_at": "2015-11-13T17:02:56Z",
    "updated_at": "2016-06-08T16:41:26Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
      }
    },
    "service_instance": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "details": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
    },
    "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"
    }
  }
}

Example Key Credential Binding Response

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

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "name": "some-name",
  "type": "key",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "created_at": "2015-11-13T17:02:56Z",
    "updated_at": "2016-06-08T16:41:26Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "service_instance": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "details": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    }
  }
}

This endpoint retrieves the service credential binding by GUID.

Definition

GET /v3/service_service_credential_bindings/:guid

Query parameters

Name	Type	Description
include	list of strings	Optionally include a list of unique related resources in the response. Valid values are: app, service_instance

Permitted roles

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

List service credential bindings

Example Request

curl "https://api.example.org/v3/service_credential_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_credential_bindings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_credential_bindings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_credential_bindings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "name": "some-binding-name",
      "type": "app",
      "last_operation": {
        "type": "create",
        "state": "succeeded",
        "created_at": "2015-11-13T17:02:56Z",
        "updated_at": "2016-06-08T16:41:26Z"
      },
      "metadata": {
        "annotations": {
          "foo": "bar"
        },
        "labels": {
          "baz": "qux"
        }
      },
      "relationships": {
        "app": {
          "data": {
            "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
          }
        },
        "service_instance": {
          "data": {
            "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        },
        "details": {
          "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
        },
        "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",
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "name": "some-key-name",
      "type": "key",
      "last_operation": {
        "type": "create",
        "state": "succeeded",
        "created_at": "2015-11-13T17:02:56Z",
        "updated_at": "2016-06-08T16:41:26Z"
      },
      "metadata": {
        "annotations": {
          "foo": "bar"
        },
        "labels": { }
      },
      "relationships": {
        "service_instance": {
          "data": {
            "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_credential_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "details": {
          "href": "https://api.example.org/v3/service_credential_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62/details"
        },
        "service_instance": {
          "href": "https://api.example.org/v3/service_instances/8bf356j3-9e18-45b1-3333-124163f31f9e"
        }
      }
    }
  ]
}

This endpoint retrieves the service credential bindings the user has access to.

Definition

GET /v3/service_credential_bindings

Query parameters

Name	Type	Description
names	list of strings	Comma-delimited list of service credential binding names to filter by
service_instance_guids	list of strings	Comma-delimited list of service instance guids to filter by
service_instance_names	list of strings	Comma-delimited list of service instance names to filter by
app_guids	list of strings	Comma-delimited list of app guids to filter by
app_names	strings	Comma-delimited list of app names to filter by
service_plan_guids	list of strings	Comma-delimited list of service plan guids to filter by
service_plan_names	list of strings	Comma-delimited list of service plan 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
type	list of strings	Type of credential binding to filter by. Valid values are: app or key
guids	list of strings	Comma-delimited list of service route binding guids to filter by
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
include	list of strings	Optionally include a list of unique related resources in the response. Valid values are: app, service_instance
label_selector	string	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, and name

Permitted roles

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

Update a service credential binding

Example Request

curl "https://api.example.org/v3/service_credential_bindings/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "metadata": {
      "labels": {"foo": "bar"},
      "annotations": {"baz": "qux"}
    }
  }'

Example Response

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

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "name": "some-name",
  "type": "app",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "created_at": "2015-11-13T17:02:56Z",
    "updated_at": "2016-06-08T16:41:26Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
      }
    },
    "service_instance": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "details": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

This endpoint updates a service credential binding with labels and annotations.

Definition

PATCH /v3/service_credential_bindings/:guid

Optional parameters

Name	Type	Description
metadata.labels	label object	Labels applied to the service credential binding
metadata.annotations	annotation object	Annotations applied to the service credential binding

Permitted roles

Admin
Space Developer

Delete a service credential binding

Example Request

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

Example Response for User-provided Service Instances

HTTP/1.1 204 No Content

Example Response for Managed Service Instance

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint deletes a service credential binding. When deleting credential bindings originated from user provided service instances, the delete operation does not require interactions with service brokers, therefore the API will respond synchronously to the delete request.

Definition

DELETE /v3/service_credential_bindings/:guid

Permitted Roles

Admin
Space Developer

Get a service credential binding details

Example Request

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

Example Credential Binding Details Response

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

{
  "credentials": {
    "connection": "mydb://user@password:example.com"
  },
  "syslog_drain_url": "http://syslog.example.com/drain",
  "volume_mounts": ["/vcap/data", "store"]
}

This endpoint retrieves the service credential binding details.

Definition

GET /v3/service_service_credential_bindings/:guid/details

Permitted roles

Admin
Admin Read-Only
Space Developer

Get parameters for a service credential binding

Example Request

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

Example Response

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

{
  "foo": "bar",
  "foz": "baz"
}

Queries the Service Broker for the parameters associated with this service credential binding. The broker catalog must have enabled the bindings_retrievable feature for the Service Offering. Check the Service Offering object for the value of this feature flag. This endpoint is not available for User-Provided Service Instances.

Definition

GET /v3/service_credential_bindings/:guid/parameters

Permitted roles

Admin
Admin Read-Only
Space Developer

Service Route Binding

Service route bindings are relations between a service instance and a route.

Not all service instances support route binding. In order to bind to a managed service instance, the service instance should be created from a service offering that has requires route forwarding (requires=[route_forwarding]). In order to bind to a user-provided service instance, the service instance must have route_service_url set.

The service route binding object

Example Service Route Binding object

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "route_service_url": "https://route-service-url.io",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "service_instance": {
      "data": {
        "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
      }
    },
    "route": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "route": {
      "href": "https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the service route binding
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
route_service_url	string	The URL for the route service
metadata.labels	label object	Labels applied to the service route binding
metadata.annotations	annotation object	Annotations applied to the service route binding
relationships.service_instance	to-one relationship	The service instance that the route is bound to
relationships.route	to-one relationship	The route that the service instance is bound to
links	links object	Links to related resources

Get a service route binding

Example Request

curl "https://api.example.org/v3/service_route_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",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "route_service_url": "https://route-service-url.io",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "service_instance": {
      "data": {
        "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
      }
    },
    "route": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "route": {
      "href": "https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
    }
  }
}

This endpoint retrieves the service route binding by GUID.

Definition

GET /v3/service_route_bindings/:guid

Query parameters

Name	Type	Description
include	list of strings	Optionally include a list of unique related resources in the response. Valid values are: route, service_instance

Permitted roles

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

List service route bindings

Example Request

curl "https://api.example.org/v3/service_route_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_route_bindings?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/service_route_bindings?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/service_route_bindings?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "4ac1a475-0f4d-4e4b-8ff6-957c94f68211",
        "route_service_url": "https://some-route-1.api.example.org",
        "created_at": "2020-09-08T08:55:59Z",
        "updated_at": "2020-09-08T08:55:59Z",
        "last_operation": null,
        "metadata": {
          "annotations": {
            "foo": "bar"
          },
          "labels": {
            "baz": "qux"
          }
        },
        "relationships": {
          "service_instance": {
            "data": {
              "guid": "39903ed2-6476-4c78-843a-0195f5fc4ccd"
            }
          },
          "route": {
            "data": {
              "guid": "15697508-cb68-4d88-9f19-85fc53851571"
            }
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/service_route_bindings/4ac1a475-0f4d-4e4b-8ff6-957c94f68211"
          },
          "service_instance": {
            "href": "https://api.example.org/v3/service_instances/39903ed2-6476-4c78-843a-0195f5fc4ccd"
          },
          "route": {
            "href": "https://api.example.org/v3/routes/15697508-cb68-4d88-9f19-85fc53851571"
          },
          "parameters": {
            "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
          }
        }
      },
      {
        "guid": "bdf63c4f-85af-4c20-bea9-e9def7d57dab",
        "route_service_url": "https://some-route-2.api.example.org",
        "created_at": "2020-09-08T09:13:51Z",
        "updated_at": "2020-09-08T09:13:51Z",
        "last_operation": null,
        "metadata": {
          "annotations": {
            "foo": "bar"
          },
          "labels": {
            "baz": "qux"
          }
        },
        "relationships": {
          "service_instance": {
            "data": {
              "guid": "f957dc7c-46d1-4a3f-973d-71ce5fdec788"
            }
          },
          "route": {
            "data": {
              "guid": "75ebe2a1-04b0-407b-b33c-733388fc7aa4"
            }
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/service_route_bindings/bdf63c4f-85af-4c20-bea9-e9def7d57dab"
          },
          "service_instance": {
            "href": "https://api.example.org/v3/service_instances/f957dc7c-46d1-4a3f-973d-71ce5fdec788"
          },
          "route": {
            "href": "https://api.example.org/v3/routes/75ebe2a1-04b0-407b-b33c-733388fc7aa4"
          }
        }
      }
    ]
  }

This endpoint retrieves the service route bindings the user has access to.

Definition

GET /v3/service_route_bindings

Query parameters

Name	Type	Description
route_guids	list of strings	Comma-delimited list of route guids to filter by
service_instance_guids	list of strings	Comma-delimited list of service instance guids to filter by
service_instance_names	list of strings	Comma-delimited list of service instance names to filter by
label_selector	string	A query string containing a list of label selector requirements
guids	list of strings	Comma-delimited list of service route binding guids to filter by
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
include	list of strings	Optionally include a list of unique related resources in the response. Valid values are: route, service_instance
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

Create a service route binding

Example Request

curl "https://api.example.org/v3/service_route_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "metadata": {
      "annotations": {
        "foo": "bar"
      },
      "labels": {
        "baz": "qux"
      }
    },
    "relationships": {
      "route": {
        "data": {
          "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
        }
      },
      "service_instance": {
        "data": {
          "guid": "e0e4417c-74ee-11ea-a604-48bf6bec2d78"
        }
      }
    },
    "parameters": {
      "key1": "value1",
      "key2": "value2"
    }
  }'

Example Response for Managed Service Instance

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

Example Response for User-Provided Service Instance

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

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "route_service_url": "https://route-service-url.io",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "service_instance": {
      "data": {
        "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
      }
    },
    "route": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "route": {
      "href": "https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
    }
  }
}

This endpoint creates a new route service binding. The service instance and the route must be in the same space.

To bind a route to a user-provided service instance, the service instance must have the route_service_url property set.

To bind a route to a managed service instance, the service offering must be bindable, and the service offering must have route_forwarding set in the requires property.

Definition

POST /v3/service_route_bindings

Required parameters

Name	Type	Description
relationships.route	to-one relationship	The route to bind
relationships.service_instance	to-one relationship	The service instance to bind

Optional parameters for managed service instances

Name	Type	Description
parameters	object	A JSON object that is passed to the service broker
metadata.labels	label object	Labels applied to the service route binding
metadata.annotations	annotation object	Annotations applied to the service route binding

Permitted roles

Admin
Space Developer

Update a service route binding

Example Request

curl "https://api.example.org/v3/service_route_bindings/[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": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "route_service_url": "https://route-service-url.io",
  "last_operation": {
    "type": "create",
    "state": "succeeded",
    "description": "Operation succeeded",
    "updated_at": "2020-03-10T15:49:32Z",
    "created_at": "2020-03-10T15:49:29Z"
  },
  "metadata": {
    "annotations": {
      "foo": "bar"
    },
    "labels": {
      "baz": "qux"
    }
  },
  "relationships": {
    "service_instance": {
      "data": {
        "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
      }
    },
    "route": {
      "data": {
        "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "route": {
      "href": "https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13"
    },
    "parameters": {
      "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
    }
  }
}

This endpoint updates a service route binding with labels and annotations.

Definition

PATCH /v3/service_route_bindings/:guid

Optional parameters

Name	Type	Description
metadata.labels	label object	Labels applied to the service route binding
metadata.annotations	annotation object	Annotations applied to the service route binding

Permitted roles

Admin
Space Developer

Delete a service route binding

Example Request

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

Example Response for User-provided Service Instances

HTTP/1.1 204 No Content

Example Response for Managed Service Instance

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint deletes a service route binding. When deleting route bindings originating from user provided service instances, the delete operation does not require interactions with service brokers, therefore the API will respond synchronously to the delete request. Consequently, deleting route bindings from managed service instances responds with a job which can be used to track the progress of the delete operation.

Definition

DELETE /v3/service_route_bindings/:guid

Permitted Roles

Admin
Space Developer

Get parameters for a route binding

Example Request

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

Example Response

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

{
  "foo": "bar",
  "foz": "baz"
}

Queries the Service Broker for the parameters associated with this service route binding. The broker catalog must have enabled the bindings_retrievable feature for the Service Offering. Check the Service Offering object for the value of this feature flag. This endpoint is not available for User-Provided Service Instances.

Definition

GET /v3/service_route_bindings/:guid/parameters

Permitted roles

Admin
Admin Read-Only
Space Developer

Service Usage Events

Service usage events are a record of changes in the usage of services. For example, service usage events are recorded when a service instance is created, updated, and deleted. They may contain information about the service instance in question and the associated space, service broker, and service offering.

Usage events are typically used by billing and chargeback applications.

The service usage event object

Example Service Usage Event object

{
  "guid": "c9976002-96f4-435a-888e-db1e1178df62",
  "created_at": "2020-05-28T12:34:56Z",
  "updated_at": "2020-05-28T12:34:56Z",
  "state": "CREATED",
  "space": {
    "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
    "name": "name-1664"
  },
  "organization": {
    "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
  },
  "service_instance": {
    "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
    "name": "name-1982",
    "type": "managed_service_instance"
  },
  "service_plan": {
    "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
    "name": "name-1983"
  },
  "service_offering": {
    "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
    "name": "label-64"
  },
  "service_broker": {
    "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
    "name": "name-2929"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_usage_events/c9976002-96f4-435a-888e-db1e1178df62"
    }
  }
}

Name	Type	Description
guid	uuid	Unique identifier for the event
created_at	timestamp	The time with zone when the event occurred
updated_at	timestamp	Identical to created_at (events are created, never updated)
state	string or null	Current state of the service that this event pertains to, if applicable
space.guid	string or null	Unique identifier of the space that this event pertains to, if applicable
space.name	string or null	Name of the space that this event pertains to, if applicable
organization.guid	string or null	Unique identifier of the org that this event pertains to, if applicable
service_instance.guid	string or null	Unique identifier of the service instance that this event pertains to, if applicable
service_instance.name	string or null	Name of the service instance that this event pertains to, if applicable
service_instance.type	string or null	Type of the service instance that this event pertains to, if applicable
service_plan.guid	string or null	Unique identifier of the service plan that this event pertains to, if applicable
service_plan.name	string or null	Name of the service plan that this event pertains to, if applicable
service_offering.guid	string or null	Unique identifier of the service offering that this event pertains to, if applicable
service_offering.name	string or null	Name of the service offering that this event pertains to, if applicable
service_broker.guid	string or null	Unique identifier of the service broker that this event pertains to, if applicable
service_broker.name	string or null	Name of the service broker that this event pertains to, if applicable
links	links object	Links to related resources

Get a service usage event

Example Request

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

Example Response

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

{
  "guid": "c9976002-96f4-435a-888e-db1e1178df62",
  "created_at": "2020-05-28T12:34:56Z",
  "updated_at": "2020-05-28T12:34:56Z",
  "state": "CREATED",
  "space": {
    "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
    "name": "name-1664"
  },
  "organization": {
    "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
  },
  "service_instance": {
    "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
    "name": "name-1982",
    "type": "managed_service_instance"
  },
  "service_plan": {
    "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
    "name": "name-1983"
  },
  "service_offering": {
    "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
    "name": "label-64"
  },
  "service_broker": {
    "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
    "name": "name-2929"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_usage_events/c9976002-96f4-435a-888e-db1e1178df62"
    }
  }
}

Retrieve a service usage event.

Definition

GET /v3/service_usage_events/:guid

Permitted Roles

Admin
Admin Read-Only
Global Auditor

List service usage events

Example Request

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

Example Response

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

{
  "pagination": {
    "total_results": 2,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_usage_events?page=1&per_page=1"
    },
    "last": {
      "href": "https://api.example.org/v3/service_usage_events?page=2&per_page=1"
    },
    "next": {
      "href": "https://api.example.org/v3/service_usage_events?page=2&per_page=1"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "c9976002-96f4-435a-888e-db1e1178df62",
      "created_at": "2020-05-28T12:34:56Z",
      "updated_at": "2020-05-28T12:34:56Z",
      "state": "CREATED",
      "space": {
        "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
        "name": "name-1664"
      },
      "organization": {
        "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
      },
      "service_instance": {
        "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
        "name": "name-1982",
        "type": "managed_service_instance"
      },
      "service_plan": {
        "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
        "name": "name-1983"
      },
      "service_offering": {
        "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
        "name": "label-64"
      },
      "service_broker": {
        "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
        "name": "name-2929"
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_usage_events/c9976002-96f4-435a-888e-db1e1178df62"
        }
      }
    }
  ]
}

Retrieve all service usage events the user has access to.

Definition

GET /v3/service_usage_events

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 value is created_at
after_guid	string	Filters out events before and including the event with the given guid
guids	list of strings	Comma-delimited list of usage event guids to filter by
service_instance_types	list of strings	Comma-delimited list of service instance types to filter by; valid values are managed_service_instance and user_provided_service_instance
service_offering_guids	list of strings	Comma-delimited list of service offering guids to filter by
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

Permitted Roles

All Roles

Purge and seed service usage events

Example Request

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

Example Response

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

Destroys all existing events. Populates new usage events, one for each existing service instance. All populated events will have a created_at value of current time. There is the potential race condition if service instances are currently being created or deleted. The seeded usage events will have the same guid as the service instance.

Definition

POST /v3/service_usage_events/actions/destructively_purge_all_and_reseed

Permitted Roles

Admin

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"
    },
    "apply_manifest": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
      "method": "POST"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

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

Create a space

Example Request

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

Example Response

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

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    },
    "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"
    },
    "apply_manifest": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
      "method": "POST"
    }
  },
  "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	label object	Labels applied to the space
metadata.annotations	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"
    },
    "apply_manifest": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
      "method": "POST"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

This endpoint retrieves the specified space object.

Definition

GET /v3/spaces/:guid

Query parameters

Name	Type	Description
include	list of strings	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"
        },
        "apply_manifest": {
          "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
          "method": "POST"
        }
      },
      "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"
        },
        "apply_manifest": {
          "href": "https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9/actions/apply_manifest",
          "method": "POST"
        }
      },
      "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	A query string containing a list of label selector requirements
include	string	Optionally include a list of unique related resources in the response; valid value is organization
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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"
    },
    "apply_manifest": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
      "method": "POST"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

PATCH /v3/spaces/:guid

Optional parameters

Name	Type	Description
name	string	New space name
metadata.labels	label object	Labels applied to the space
metadata.annotations	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	timestamp	The time with zone when the space quota was created
updated_at	timestamp	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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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 200 OK
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
guid	uuid	Unique identifier for the stack
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
name	string	The name of the stack
description	string	The description of the stack
metadata.labels	label object	Labels applied to the stack
metadata.annotations	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	label object	Labels applied to the stack
metadata.annotations	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
names	list of strings	Comma-delimited list of app names to filter by
page	integer	Page to display; valid values are integers >= 1
per_page	integer	Number of results per page; valid values are 1 through 5000
order_by	string	Value to sort by. Defaults to ascending; prepend with - to sort descending Valid values are created_at, updated_at, and name
label_selector	string	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	label object	Labels applied to the stack
metadata.annotations	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
guid	uuid	Unique identifier for the task
created_at	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
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
state	string	State of the task Possible states are PENDING, RUNNING, SUCCEEDED, CANCELING, and FAILED
memory_in_mb	integer	Amount of memory to allocate for the task in MB
disk_in_mb	integer	Amount of disk to allocate for the task in MB
result	object	Results from the task
result.failure_reason	string	Null if the task succeeds, contains the error message if it fails
droplet_guid	uuid	The guid of the droplet that will be used to run the command
relationships.app	timestamp	The app the task belongs to
metadata.labels	label object	Labels applied to the task
metadata.annotations	annotation object	Annotations applied to the task
links	links object	Links to related resources

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	uuid	The guid of the process that will be used as a template	null
metadata.labels	label object	Labels applied to the package
metadata.annotations	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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	label object	Labels applied to the task
metadata.annotations	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	timestamp	The time with zone when the object was created
updated_at	timestamp	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
metadata.labels	label object	Labels applied to the user
metadata.annotations	annotation object	Annotations added to the user
links	links object	Links to related resources

Create a user

Creating a user requires one value, a GUID. This creates a user in the Cloud Controller database.

Generally, the GUID should match the GUID of an already-created user in the UAA database, though this is not required.

Example Request

curl "https://api.example.org/v3/users" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
  }'

Example Response

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

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "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	label object	Labels applied to the user
metadata.annotations	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
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	A query string containing a list of label selector requirements
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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	label object	Labels applied to the app
metadata.annotations	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

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.",
  "deployable": true,
  "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	timestamp	The time with zone when the object was created
updated_at	timestamp	The time with zone when the object was last updated
description	string	A short description of the reason for revision
deployable (experimental)	boolean	Indicates if the revision’s droplet is staged and the revision can be used to create a deployment
relationships.app	to-one relationship	The app the revision is associated with
metadata.labels	label object	Labels applied to the revision
metadata.annotations	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	list 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.",
  "deployable": true,
  "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

Get environment variables for a revision

Example Request

curl "https://api.example.org/v3/revisions/[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/revisions/[guid]/environment_variables"
    },
    "revision": {
      "href": "https://api.example.org/v3/revisions/[guid]"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/[app_guid]"
    }
  }
}

Retrieve the environment variables that are associated with the revision.

Definition

GET /v3/revisions/:guid/environment_variables

Permitted roles

Admin
Admin Read-Only
Space Developer

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.",
      "deployable": true,
      "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	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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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.",
      "deployable": true,
      "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.",
  "deployable": true,
  "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	label object	Labels applied to the revision
metadata.annotations	annotation object	Annotations applied to the revision

Permitted roles

Admin
Space Developer

Sidecars

Sidecars are additional operating system processes that are run in the same container as a process.

Use cases for sidecars

Sidecars are useful for any app processes that need to communicate with another within the same container or are otherwise dependent on each other. Some use cases are:

• Two or more processes that require access to a shared file
• An Application Performance Monitoring (APM) tool that attaches to a dependent app’s processes
• Two or more processes that communicate via a local socket

Steps to create a sidecar

The recommended way to create sidecars for your app is with a 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	list 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	timestamp	The time with zone when the object was created
updated_at	timestamp	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	list 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	list 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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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
created_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats (experimental)	timestamp	Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators

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

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 database as the V2 API. Though resources may be presented differently and have different interaction patterns, the internal state of CF is the same across both APIs. If you create an organization using the V3 API, it will be visible to the V2 API, and vice-versa.

If you have questions, need help, or want to chat about the upgrade process, please reach out to us in Cloud Foundry Slack.

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. The processes can be scaled independently, and stats be retrieved independently.
3. An application might not be running with its most recent package or droplet

Starting Apps

In the V2 API, starting an app (PUT /v2/apps/:GUID with state: STARTED) will automatically stage new packages into droplets. In V3, starting an app will only run the app’s current droplet. This change gives clients more control over what package to stage and when to stage it.

To reproduce the V2 start behavior in V3:

1. List packages and filter on package state with value READY and order by recency.
2. If a package has been turned into a droplet (see this endpoint) this means it has been staged already. In V2 workflows, this would mean this package is what the current droplet is running.
3. Stage the package by creating a build. This turns your package into a droplet.
4. Update the app’s current droplet to the selected droplet. This droplet will be run when the app starts.
5. Change the app’s state to started

This gives V3 users more flexibility when managing applications. The following diagram shows many different flows for starting an app.

Apps can upload multiple packages, stage multiple droplets, roll back to older droplets, and other complicated workflows.

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, 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.

Service related endpoints such as service instance, service credential binding and service route binding may create jobs that transition to state POLLING after PROCESSING. This state reflects the polling of the last operation from the service broker. For clients that want to report the outcome of this asynchronous operation, poll the job in the Location header until its state is no longer POLLING.

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.

Filtering inequalities has changed in V3: V3 dispenses with the q= preamble, uses created_ats instead of timestamp and uses bracket operators ([lt], [gt], [lte], [gte]). For example, to request all audit events occurring on New Year’s Day, one would use the following query: GET /v3/audit_events?created_ats[lt]=2020-01-02T00:00:00Z&created_ats[gt]=2019-12-31T23:59:59Z.

The corresponding V2 query would be GET /v2/events?q=timestamp<2020-01-02T00:00:00Z&q=timestamp>2019-12-31T23:59:59Z.

Filtering on equality has also changed: V3 dispenses with the q= preamble and uses the pluralized field (e.g. names) on the left side of the equals sign. For filtering on inclusion in a set, V3 allows passing multiple values separated by commas.

For example, to request the organizations by their name (“finance” and “marketing”), one would use the following query: /v3/organizations?names=finance,marketing

The corresponding V2 query would be GET /v2/organizations?q=name%20IN%20finance,marketing

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

In addition, some resources provide the possibility of including specified fields of a related resource.

For example, to include the service broker name and guid in the service offering’s response: cf curl /v3/service_offerings/:guid?fields[service_broker]=name,guid

Read more about the include parameter and the fields parameter.

Resource Summaries

V2 provided several endpoints that returned rolled-up summaries (e.g. /v2/spaces/:guid/summary for a space summary, or /v2/organizations/:guid/summary for an organization summary). Although convenient, these endpoints have been largely removed from V3, for they were computationally expensive and often returned much more information than needed.

In V3, to enable better API performance, these usage patterns are deliberately disallowed. Instead, clients are encouraged to think more carefully about which information they need and to fetch that information with multiple API calls and/or by making use of the include parameter or the fields parameter on certain endpoints.

In V2, summary endpoints provided a way to fetch all resources associated with a parent resource. In V3, fetch the summary though the associated resource and filter by the parent resource. See below for examples of summaries in V3.

Replacing the space summary endpoint

• To fetch all apps in a space, use GET /v3/apps?space_guids=<space-guid>. Passing include=space will include the space resource in the response body.
• To fetch all service offerings in a space use GET /v3/service_offerings?space_guids=<space-guid>. Use the experimental fields parameter to include related information in the response body.
• To fetch all service instances in a space use GET /v3/service_instances?space_guids=<space-guid>. Use the experimental fields parameter to include related information in the response body.

Replacing the space summary response for service instances

Similar fields to what /v2/spaces/:guid/summary was offering for services are available from v3 endpoints.

The table below describes the query parameters needed to retrieve some of those fields using /v3/service_instances endpoint. Same query parameters are available on the request for a single resource.

V2 summary fields	V3 query	V3 response fields
services[].service_plan.guid	fields[service_plan]=guid	resources[].included.service_plans[].guid
services[].service_plan.name	fields[service_plan]=name	resources[].included.service_plans[].name
services[].service_plan.service.guid	fields[service_plan.service_offering]=guid	resources[].included.service_offerings[].guid
services[].service_plan.service.label	fields[service_plan.service_offering]=name	resources[].included.service_offerings[].name
services[].service_broker_name	fields[service_plan.service_offering.service_broker]=name	resources[].included.service_brokers[].name
shared_from.space_guid	fields[space]=guid	resources[].included.spaces[].guid
shared_from.space_name	fields[space]=name	resources[].included.spaces[].name
shared_from.organization_name	fields[space.organization]=name	resources[].included.organizations[].name

The table below describes the query parameters needed to retrieve the sharing information using /v3/service_instances/:guid/relationships/shared_spaces endpoint.

V2 summary fields	V3 query	V3 response fields
shared_to.space_guid	fields[space]=guid	included.spaces[].guid
shared_to.space_name	fields[space]=name	included.spaces[].name
shared_to.organization_name	fields[space.organization]=name	included.organizations[].name

The existing bound_app_count field can be found by using the usage summary endpoint

Read more about the fields parameter.

Replacing the user summary endpoint

• The user summary was useful for finding organizations and spaces where a user had roles. In V3, with the introduction of the role resource, you can use GET /v3/roles?user_guids=<user-guid> to list a user’s roles. Passing include=space,organization will include the relevant spaces and organizations in the response body.

Usage summary endpoints

There are still a couple of endpoints in V3 that provide a basic summary of instance and memory usage. See the org summary and platform summary endpoints.

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.

Builds

Builds increase the flexibility and granularity of control available to clients crafting stagings workflows. For example:

• Staging older packages instead of always staging the most recent package
• Staging packages without having to stop an application
• Staging packages to produce droplets without setting them as the current droplet for an app
• Staging packages into droplets for use in tasks and/or rolling deployments

Read more about the builds resource.

Deployments

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

Read more about the deployments 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.

Read more about the manifest resource.

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.

Service Route Bindings

There is a new resource service route binding that represents a binding between a route and a service instance.

Creation/Deletion of these bindings is therefore done via that endpoint in v3.

This resource also supports metadata both in create and update requests. Audit event of type audit.service_route_binding.update is recorded when metadata update is requested.

It has a nested resource for fetching binding parameters from the broker. Parameters are only set during creation.

Read more about the service route binding 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.

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	Audit Events in V3
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	Security Groups in V3
Services	Service Offerings	Service Offerings in V3
Service Bindings, Service Keys	Service Keys
Service Brokers	Service Brokers	Service Brokers in V3
Service Instances, User-Provided Service Instances	Service Instances
Service Plans	Service Plans	Service Plans in V3
Service Plan Visibilities	Service Plan Visibility	Service Plan Visibility in V3
Spaces	Spaces
Space Quota Definitions	Space Quotas	Space Quotas in V3
Stacks	Stacks
Usage Events	Usage Events	Usage Events in V3
Users	Roles, Users	Users and Roles in V3

Audit Events in V3

In V2, these were called “events” (e.g. /v2/events). In V3, we adopt the term “audit events” to better distinguish them from usage events.

V2 audit events contained information about the “actee” (the resource that the event affected). V3 audit events refer to the affected resource as the “target”.

V2 audit events had a timestamp field. In V3, this field has been renamed to created_at for consistency with other resources. The value is the same.

In general, V3 audit events contain all of the same information that they contained in V2, but the JSON is structured a little differently. In particular:

• The metadata field has been renamed to data.
• Actor-related fields have been grouped into an object under the actor key (e.g. actor.type instead of actor_type).
• Actee-related fields have been grouped under the target key (e.g. target.type instead of actee_type).

At the time of this writing, V3 does not support greater-than or less-than filtering for the created_at field. In V2, this was supported via /v2/events?q=timestamp>some_timestamp. There are plans support this in the future.

V3 endpoints attempt to report audit events in the same way as V2 endpoints did. A notable case where this was not possible is for the audit.app.restage event. Read more about restaging in V3.

Read more about the audit event resource.

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.

Security Groups in V3

In V2, security groups which apply to all spaces in a Cloud Foundry deployment are termed “default”, as in “default for running apps” and “default for staging apps”. For example, to apply a default security group to all apps in the running lifecycle, one would PUT /v2/config/running_security_groups/:guid

In V3, security groups which apply to all spaces in a Cloud Foundry deployment are termed “global”, as in “globally-enabled running apps” and “globally-enabled staging apps.” For example, to apply a security group globally to all apps in the running lifecycle, one would PATCH /v3/security_groups/:guid with a body specifying the globally_enabled key. See here for an example.

In V2, on creation, one can specify the spaces to which the security group applies, but not whether it applies globally (by default). To set the group globally to all spaces in the foundation one would PUT /v2/config/running_security_groups/43e0441d-c9c1-4250-b8d5-7fb624379e02.

In V3, on creation, one can both specify the spaces to which it applies and also whether it applies globally (to staging and/or running) by specifying the globally_enabled key. See here for more information.

In V2, the endpoint to apply a security group to a space only includes the lifecycle (“running” or “staging”) explicitly when applying to “staging” (“running” is the default lifecycle). For example, to unbind a security group from the running lifecycle, one would DELETE /v2/security_groups/:guid/spaces/:space_guid, from the staging lifecycle, DELETE /v2/security_groups/:guid/staging_spaces/:space_guid.

In V3, the endpoint to apply a security group to a space includes the lifecycle. For example to unbind a security group from the running lifecycle, one would DELETE /v3/security_groups/:guid/relationships/running_spaces/:space_guid.

Service Brokers in V3

Create, Update and Delete

In V3 these endpoints are now asynchronous. See asynchronous operations and service broker jobs for more information.

Read more about the service broker resource.

Service Instances in V3

Combining managed and user-provided service instances

In v2, two different endpoints /v2/service_instances and /v2/user_provided_service_instances were used to perform operations on service instances according to their types.

In v3, all service instance operations are performed using the service instance resource, regardless of the type. Service instances can be of type managed when it is an instantiation of a service offering registered with CF or user-provided when it describes an instance of an offering that is not registered with CF. The type filter can be used to separately list each type.

The required parameters when creating and updating a service instance are different for each type as defined in their respective documentation.

Object

The structure of the service instances object as well as some attribute names have changed from V2 to V3. Each service instance type has type specific fields. Certain fields are omitted when they do not apply to the type of the service instance.

V2	V3
type valid values managed_service_instance and user_provided_service_instance	type valid values managed and user-provided
entity.service_plan_guid	relationships.service_plan.data.guid
entity.space_guid	relationships.space.data.guid

User provided service instance credentials

The credentials field for user provided service instances is not included in the response object of service_instances. /v3/service_instances/:guid/credentials can be used to retrieve the credentials.

Read more about the service instance credential.

Response mode

When operating on service instances of type user-provided the API will respond synchronously for all operations.

When the service instance type is managed the API will respond asynchronously and the operation might include communicating to the service broker. Read more about async responses here.

Listing bindings

In v2, there were specific endpoints /v2/service_instances/:guid/service_bindings, /v2/service_instances/:guid/service_keys and /v2/user_provided_service_instances/:guid/service_bindings to retrieve the service bindings and service keys for managed and user-provided service instances.

In v3, the service credential bindings can be filtered by service_instance_guids to retrieve the bindings of any service instance.

Service instance route bindings

In v2, binding a service instance to a route was done as a relationship request for the service instance.

In v3, there is a new resource service route binding that represents a binding between a route and a service instance. Creation and deletion of route bindings is therefore done via that endpoint in v3.

Audit events for route bindings have changed as follows:

V2	V3
audit.service_instance.bind_route	audit.service_route_binding.start_create (async only) audit.service_route_binding.create
audit.service_instance.unbind_route	audit.service_route_binding.start_delete (async only) audit.service_route_binding.delete

Read more about the service instance resource.

Service Bindings in V3

Combining service bindings and service keys

In v2, two different endpoints /v2/service_bindings and /v2/service_keys were used to perform bindings operations for service instances.

In v3, all service bindings that are not route bindings are performed using the service credential bindings resource. Service credential bindings can be of type app when it is a binding between a service instance and an application or key when it only retrieves the credentials of the service instance. The type filter can be used to list separately each type.

The required parameters when creating a service credential binding are different for each type as defined in the documentation.

Object

The structure of the service credential binding object follows V3 pattern. If the type is app the object will contain a relationship to the app.

Retrieving service credential bindings details

The credentials, syslog_drain_url and volume_mounts fields for service credential bindings are not included in the response object of service credential bindings. /v3/service_credential_bindings/:guid/details can be used to retrieve the credentials.

Read more about the service credential binding details.

Service key operations

In v2, all service keys operations were synchronous.

In v3, all service credential bindings, including those of type key are asynchronous if possible.

Response mode

When operating on service credential bindings of user-provided service instances the API will respond synchronously for all operations.

When operating on service credential bindings of managed service instances the API will respond asynchronously and the operation might include communicating to the service broker. Read more about async responses here.

Audit events

Audit events of type audit.service_key.start_create and audit.service_key.start_delete have been added to track when an async create or delete key service credential binding operation has started.

Audit events of type audit.service_binding.update and audit.service_key.update are recorded when metadata update is requested.

Read more about the service credential binding resource.

Service Offerings in V3

Services resource is now replaced by service offerings resource at /v3/service_offerings

Some services related endpoints nested in other resources have been translated to filters on service_offerings, with the advantage that filters accept multiple values and can be combined.

GET /v2/organizations/:guid/services is now GET /v3/service_offerings?organization_ids=guid.

GET /v2/spaces/:guid/services is now GET /v3/service_offerings?space_ids=guid

GET /v2/services/:guid/service_plans is now a filter on the service plan resource: GET /v3/service_plans?service_offering_guids=guid. This link can also be found in the object’s links section.

In V2, service_broker_name was returned in the response. V3 returns this value only if requested using the fields syntax. Refer to service offerings resource for further information. A link to the Service Broker resource is included in the object’s links section.

The structure of the service offering object as well as some attribute names have changed from V2 to V3:

V2	V3
label	name
active	available
bindable	broker_catalog.features.bindable
extra	shareable, broker_catalog.metadata
unique_id	broker_catalog.id
plan_updateable	broker_catalog.features.plan_updateable
instances_retrievable	broker_catalog.features.instances_retrievable
bindings_retrievable	broker_catalog.features.bindings_retrievable
service_broker_guid	relationships.service_broker.data.guid

Read more about the service offering resource.

Service Plans in V3

Some service plans related endpoints nested in other resources have been translated to filters on service plans, with the advantage that filters accept multiple values and can be combined.

GET /v2/services/:guid/service_plans -> GET /v3/service_plans?service_offering_guids=guid

Changing plan visibility to Public is not a PUT operation anymore. To change visibility use the service plan visibility resource

The structure of the service plan object as well as some attribute names have changed from V2 to V3:

V2	V3
active	available
bindable	broker_catalog.features.bindable
extra	broker_catalog.metadata
public	visibility_type == 'public' (see visibility types)
unique_id	broker_catalog.id
plan_updateable	broker_catalog.features.plan_updateable
service_instances_url	use service_plan_guids or service_plan_names filter on service instances resource
service_url	links.service_offering.href
service_guid	relationships.service_offering.data.guid

Some filters were renamed and changed to accept a list of values:

V2	V3
service_guid	service_offering_guids
service_instance_guid	service_instance_guids
service_broker_guid	service_broker_guids
unique_id	broker_catalog_ids

Read more about the service plan resource.

Service Plan Visibility in V3

v2/service_plan_visibilities has been replaced in v3 with a nested resource v3/service_plans/:guid/visibility

This new resource has a type, and can have a list of organizations a space or be of type public

Read more about the service plan visibility resource.

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.

Usage Events in V3

This section covers changes in both app usage events and service usage events.

The V2 service_guid field for service usage events is now renamed to service_offering.guid.

The V2 service_label field for service usage events is now renamed to service_offering.label.

The V2 app_guid field for app usage events is now renamed to process.guid.

The V2 experimental field parent_app_guid for app usage events was used to identify a backing V3 app if present. In V3, this field has been renamed to app.guid and is no longer experimental.

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.

In the v2, when an Org Manager gives a person an Org or Space role, that person automatically receives Org User status in that org. This is no longer the case in the v3 API.

Read more about users and roles.

Deprecated Endpoints

The specialized /v2/apps/:guid/restage endpoint is replaced by the builds resource. Builds allow finer-grained control and increased flexibility when staging packages into droplets. The V3 API avoids making assumptions about which package/droplet to use when staging or running an app and thus leaves it up to clients.

Restage

The specialized /v2/apps/:guid/restage endpoint is replaced by the builds resource. Builds allow finer-grained control and increased flexibility when staging packages into droplets. The V3 API avoids making assumptions about which package/droplet to use when staging or running an app and thus leaves it up to clients.

Replicating Restage

1. Get newest READY package for an app:

   GET /v3/packages?app_guids=:app-guid&order_by=-created_at&states=READY

2. Stage the package:

   POST /v3/build

3. Poll build until the state is STAGED:

   GET /v3/builds/build-guid

4. Stop the app:

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

5. Set the app’s current droplet to the build’s resulting droplet:

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

6. Start app:

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

For a zero-downtime restage, you may wish to use deployments instead of stopping and starting the app.

Restage Event

Since the V3 API has no concept of a “restage”, the audit.app.restage audit event is no longer reported. Instead, the following events can be tracked:

Audit Event	Description
audit.build.create	A build is created (staging is initiated)
audit.droplet.create	A droplet is created (staging finishes successfully)
audit.app.stop	Stopping an app is initiated
audit.app.droplet.mapped	A droplet is set as the current droplet for an app
audit.app.start	Starting an app is initiated
audit.app.deployment.create	A deployment is initialized