NAV

Introduction

Overview

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

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

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

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_controller_service_permissions.read This scope provides read only access for service instance permissions

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
Space Supporter Troubleshoot and debug apps and service bindings in a space

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

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

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

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

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

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

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.

If buildpacks are not specified, then Cloud Foundry will automatically detect a compatible buildpack, based on the files in an app’s package. If a stack is not specified, then the app will default to the operator-configured default stack.

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 cflinuxfs4

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

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 resides. When a service instance is being updated, the service broker is sent the annotations of the space and organization in which the service instance resides. 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 (e.g. company.com/contacts) are sent to service brokers.

Examples may include (but are not limited to):

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:

An annotation key name must adhere to the following restrictions:

Annotation values

Annotation values must adhere to the following restrictions:

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

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

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:

A label key name must adhere to the following restrictions:

Label values

Label values must adhere to the following restrictions:

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. The maximum number of requirements in a single selector is 50.

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

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.

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:

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 query parameter would look like 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. The resulting query parameter must be encoded a second time before sending it to the API, e.g. cf curl /v3/apps?names=a%252Cb,c%252Cd.

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": "cflinuxfs4"
    }
  },
  "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": "cflinuxfs4"
    }
  },
  "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": "cflinuxfs4"
    }
  },
  "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
Space Supporter

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": "cflinuxfs4"
          }
        },
        "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": "cflinuxfs4"
          }
        },
        "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 space.organization
created_ats timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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": "cflinuxfs4"
    }
  },
  "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": "cflinuxfs4",
  "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
Space Supporter

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

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

Role Notes
Admin
Admin Read-Only
Space Developer
Space Supporter system_env_json redacted

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

Get permissions for an app

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

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

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

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": "cflinuxfs4"
    }
  },
  "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
Space Supporter

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": "cflinuxfs4"
    }
  },
  "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
Space Supporter

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": "cflinuxfs4"
    }
  },
  "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
Space Supporter

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

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

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

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

Role Notes
Admin
Space Developer
Space Supporter Can only update revisions feature

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 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, see the Cloud Foundry docs.

Audit Event Types

App lifecycle
Organization lifecycle
Route lifecycle
Service lifecycle
Service_binding lifecycle
Service_broker lifecycle
Service_dashboard_client lifecycle
Service_instance lifecycle
Service_key lifecycle
Service_plan lifecycle
Service_plan_visibility lifecycle
Service_route_binding lifecycle
Space lifecycle
User lifecycle
User_provided_service_instance lifecycle
Special events

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
Org Auditor Cannot see events which occurred in orgs that the user does not belong to
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
Space Supporter Cannot see events which occurred in spaces 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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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 Auditor
Org Manager
Space Auditor
Space Developer
Space Manager
Space Supporter

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": "bill@example.com"
  },
  "state": "STAGED",
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 1024,
  "staging_log_rate_limit_bytes_per_second": 1024,
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs4"
    }
  },
  "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
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
staging_log_rate_limit_bytes_per_second integer Log rate limit in bytes per second allocated for staging of the build
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": "bill@example.com"
  },
  "state": "STAGING",
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 1024,
  "staging_log_rate_limit_bytes_per_second": 1024,
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs4"
    }
  },
  "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
staging_log_rate_limit_bytes_per_second integer Log rate limit in bytes per second 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
Space Supporter

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": "bill@example.com"
  },
  "state": "STAGED",
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 1024,
  "staging_log_rate_limit_bytes_per_second": 1024,
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs4"
    }
  },
  "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
Space Supporter

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": "bill@example.com"
      },
      "state": "STAGING",
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 1024,
      "staging_log_rate_limit_bytes_per_second": 1024,
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": "cflinuxfs4"
        }
      },
      "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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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": "bill@example.com"
      },
      "state": "STAGING",
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 1024,
      "staging_log_rate_limit_bytes_per_second": 1024,
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": "cflinuxfs4"
        }
      },
      "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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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
Space Supporter

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": "bill@example.com"
  },
  "state": "STAGED",
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 1024,
  "staging_log_rate_limit_bytes_per_second": 1024,
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs4"
    }
  },
  "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 string Build status; valid values are FAILED or STAGED (field can only be passed by Build State Updaters)
lifecycle.data.image 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 states are: AWAITING_UPLOAD, READY
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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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:

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)
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
Space Supporter

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

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

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

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

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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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/organizations/[guid]/domains?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/organizations/[guid]/domains?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/organizations/[guid]/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

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": "cflinuxfs4",
  "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 cflinuxfs4
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": "cflinuxfs4",
  "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": "cflinuxfs4",
  "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

Role Notes
Admin
Admin Read-Only
Global Auditor Some fields are redacted
Org Manager Some fields are redacted
Space Auditor Some fields are redacted
Space Developer
Space Manager Some fields are redacted
Space Supporter Some fields are redacted

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": "cflinuxfs4",
      "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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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": "cflinuxfs4",
      "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
Space Supporter

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": "cflinuxfs4",
      "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
Space Supporter

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": "cflinuxfs4",
    "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
image string Image reference 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

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, log rate, 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: route_sharing (experimental)
Default: false
Description: When enabled, Space Developers can share routes between two spaces (even across orgs!) in which they have the Space Developer role. When disabled, Space Developers cannot share routes between two spaces.
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 perform a get on the /v2/apps/:guid/env endpoint, and both space developers and space supporters can perform a get on the /v3/apps/:guid/env and /v3/apps/:guid/environment_variables endpoints. When disabled, neither space developers nor space supporters can access these endpoints.
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 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": {}
   }
}

Retrieve an isolation segment to which the user has access. For admin, this is any isolation segment in the system. For anyone else, this is an isolation segment in the allowed list for any organization to which the user belongs.

Definition

GET /v3/isolation_segments/:guid

Permitted roles

All Roles

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 anyone else, this is the isolation segments in the allowed list for any organization to which the user belongs.

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

All Roles

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

All Roles

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
    protocol: http2
  services:
  - my-service1
  - my-service2
  - name: my-service-with-arbitrary-params
    binding_name: my-binding
    parameters:
      key1: value1
      key2: value2
  stack: cflinuxfs4
  metadata:
    annotations:
      contact: "bob@example.com jane@example.com"
    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
    log-rate-limit-per-second: 1KB
    timeout: 10
  - type: worker
    command: start-worker.sh
    disk_quota: 1G
    health-check-type: process
    instances: 2
    memory: 256M
    log-rate-limit-per-second: 1KB
    timeout: 15
- name: app2
  env:
    VAR1: value1
  processes:
  - type: web
    instances: 1
    memory: 256M
    log-rate-limit-per-second: 1KB
  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 configurations List declaring HTTP and TCP routes to be mapped to the app.
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 cflinuxfs4
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
log-rate-limit-per-second string The log rate limit for all the instances of the process;
this attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case, or -1 or 0
timeout integer Time in seconds at which the health-check will report failure

Route-level configuration

This configuration is for creating mappings between the app and a route. Each route is created if it does not already exist. The protocol will be updated for any existing route mapping.

Name Type Description
route string (Required) The route URI. Example: host.domain.com
protocol string Protocol to use for this route. Valid protocols are http1, http2, and tcp.

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: cflinuxfs4
  services:
  - my-service
  routes:
  - route: my-app.example.com
    protocol: http1
  processes:
  - type: web
    instances: 2
    memory: 512M
    log-rate-limit-per-second: 1KB
    disk_quota: 1024M
    health-check-type: http
    health-check-http-endpoint: /healthy
    health-check-invocation-timeout: 10
    health-check-interval: 5
    readiness-health-check-type: http
    readiness-health-check-http-endpoint: /ready
    readiness-health-check-invocation-timeout: 20
    readiness-health-check-interval: 5

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]" \
  --data-binary @/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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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

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

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,
    "routes": 4,
    "service_instances": 2,
    "reserved_ports": 1,
    "domains": 4,
    "per_app_tasks": 2,
    "service_keys": 1
  },
  "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

List users for an organization

Example Request
curl "https://api.example.org/v3/organizations/:guid/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/organizations/:guid/users?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/organizations/:guid/users?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/organizations/:guid/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 with a role in the specified organization.

Definition

GET /v3/organizations/:guid/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. Mutually exclusive with partial_usernames
partial_usernames list of strings Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with usernames
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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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

Organization Quotas

Organization quotas are named sets of memory, log rate, 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,
      "log_rate_limit_in_bytes_per_second": 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.log_rate_limit_in_bytes_per_second integer or null Total log rate limit allowed for all the started processes and running tasks in an organization
apps.per_app_tasks integer or null Maximum number of running tasks in an organization
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,
      "log_rate_limit_in_bytes_per_second": 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.log_rate_limit_in_bytes_per_second integer or null Total log rate limit allowed for all the started processes and running tasks in an organization null (infinite)
apps.per_app_tasks integer or null Maximum number of running tasks in an organization 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

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,
      "log_rate_limit_in_bytes_per_second": 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
Space Supporter 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,
          "log_rate_limit_in_bytes_per_second": 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,
          "log_rate_limit_in_bytes_per_second": 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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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
Space Supporter 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

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

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,
      "log_rate_limit_in_bytes_per_second": 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,
      "log_rate_limit_in_bytes_per_second": 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.log_rate_limit_in_bytes_per_second integer or null Total log rate limit allowed for all the started processes and running tasks in an organization
apps.per_app_tasks integer or null Maximum number of running tasks in an organization
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

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

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

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

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

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
username string The username for the image’s registry. Only possible for Docker package.
password string The password for the image’s registry. Only possible for Docker 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

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,
  "log_rate_limit_in_bytes_per_second": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "readiness_health_check": {
    "type": "process",
    "data": {
      "invocation_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",
  "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
  "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
version uuid Random identifier that changes every time the process will be recreated in the runtime.
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
log_rate_limit_in_bytes_per_second integer The log rate in bytes per second 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
readiness_health_check readiness health check object The readiness health check to perform on the process
relationships.app to-one relationship The app the process belongs to
relationships.revision 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.interval integer The interval in seconds between health check requests
data.endpoint string The endpoint called to determine if the app is healthy; this key is only present for http health checks

The readiness health check object

Example readiness health check object
{
  "type": "http",
  "data": {
    "endpoint": "/ready",
    "invocation_timeout": 2
  }
}

Name Type Description
type string The type of health check to perform; valid values are http, port, and process; default is process
data.invocation_timeout integer The timeout in seconds for individual health check requests for http and port health checks
data.interval integer The interval in seconds between health check requests
data.endpoint string The endpoint called to determine if the app is ready; this key is only present for http health checks

The process stats object

The process stats object provides information about the status of an individual instance of a process.

Example process stats object
{
  "type": "web",
  "index": 0,
  "state": "RUNNING",
  "usage": {
    "time": "2016-03-23T23:17:30.476314154Z",
    "cpu": 0.00038711029163348665,
    "cpu_entitlement": 0.01117396940977856,
    "mem": 19177472,
    "disk": 69705728,
    "log_rate": 0
  },
  "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
routable boolean Whether or not the instance is routable (determined by the readiness check of the app). If app readiness checks and routability are unsupported by Diego, this will return as null.
usage object Object containing actual usage data for the instance; the value is {} when usage data is unavailable
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
usage.log_rate integer The current logging usage of the instance
host string The host the instance is running on
instance_internal_ip string The internal IP address of the instance
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; the value is null when memory quota data is unavailable
disk_quota integer The current maximum disk allocated for the instance; the value is null when disk quota data is unavailable
log_rate_limit integer The current maximum log rate allocated for the instance; the value -1 is unlimited, the value is null when the log_rate_limit is unavailable
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,
  "log_rate_limit_in_bytes_per_second": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "readiness_health_check": {
    "type": "process",
    "data": {
      "invocation_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",
  "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
  "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

Role Notes
Admin
Admin Read-Only
Global Auditor Some fields are redacted
Org Manager Some fields are redacted
Space Auditor Some fields are redacted
Space Developer
Space Manager Some fields are redacted
Space Supporter Some fields are redacted

Get stats for a process

Process stats are objects that represent the individual instances of 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,
        "cpu_entitlement": 0.01117396940977856,
        "mem": 19177472,
        "disk": 69705728,
        "log_rate": 0
      },
      "host": "10.244.16.10",
      "instance_internal_ip": "10.255.93.167",
      "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",
      "log_rate_limit": null,
      "details": null
    },
    {
      "type": "web",
      "index": 1,
      "state": "STARTING",
      "usage": {
        "cpu": 0,
        "cpu_entitlement": null,
        "disk": 0,
        "log_rate": 0,
        "mem": 0,
        "time": "2016-03-23T21:34:04+00:00"
      },
      "disk_quota": null,
      "fds_quota": 16384,
      "host": "",
      "instance_internal_ip": "",
      "instance_ports": null,
      "isolation_segment": null,
      "log_rate_limit": null,
      "mem_quota": null,
      "uptime": 0,
      "details": null
      }
  ]
}

Definition

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

Permitted roles

Role Notes
Admin
Admin Read-Only
Global Auditor Some fields are redacted
Org Manager Some fields are redacted
Space Auditor Some fields are redacted
Space Developer
Space Manager Some fields are redacted
Space Supporter Some fields are redacted

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,
      "log_rate_limit_in_bytes_per_second": 1024,
      "health_check": {
        "type": "port",
        "data": {
          "timeout": null,
          "invocation_timeout": null,
          "interval": null
        }
      },
      "readiness_health_check": {
        "type": "process",
        "data": {
          "invocation_timeout": null,
          "interval": 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",
      "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
      "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,
      "log_rate_limit_in_bytes_per_second": 1024,
      "health_check": {
        "type": "process",
        "data": {
          "invocation_timeout": null,
          "interval": null
        }
      },
      "readiness_health_check": {
        "type": "http",
        "data": {
          "endpoint": "/ready",
          "invocation_timeout": 2,
          "interval": 5
        }
      },
      "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",
      "version": "74e513bb-7b9e-445c-84d5-7fea1394e611",
      "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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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,
      "log_rate_limit_in_bytes_per_second": 1024,
      "health_check": {
        "type": "port",
        "data": {
          "timeout": null,
          "invocation_timeout": null,
          "interval": null
        }
      },
      "readiness_health_check": {
        "type": "process",
        "data": {
          "invocation_timeout": null,
          "interval": 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",
      "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
      "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,
      "log_rate_limit_in_bytes_per_second": 1024,
      "health_check": {
        "type": "process",
        "data": {
          "invocation_timeout": null,
          "interval": null
        }
      },
      "readiness_health_check": {
        "type": "http",
        "data": {
          "endpoint": "/ready",
          "invocation_timeout": 2,
          "interval": 5
        }
      },
      "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",
      "version": "74e513bb-7b9e-445c-84d5-7fea1394e611",
      "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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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
Space Supporter

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,
  "log_rate_limit_in_bytes_per_second": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "readiness_health_check": {
    "type": "process",
    "data": {
      "invocation_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",
  "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
  "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
readiness_health_check readiness health check object The readiness 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
Space Supporter

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,
    "log_rate_limit_in_bytes_per_second": 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,
  "log_rate_limit_in_bytes_per_second": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "readiness_health_check": {
    "type": "process",
    "data": {
      "invocation_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",
  "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
  "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
log_rate_limit_in_bytes_per_second integer The log rate in bytes per second allocated per instance

Permitted roles

Admin
Space Developer
Space Supporter

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

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

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:

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

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

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

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

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

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
Space Supporter Can see roles in supported 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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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"
    },
    "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,
      "protocol": "tcp"
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080,
      "protocol": "tcp"
    }
 ],
  "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 either a wildcard (*) or 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,
  "protocol": "http2"
}

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
protocol string or null Protocol to use for this destination. Valid protocols are http1 or http2 if route protocol is http, tcp if route protocol is tcp. A null value will set it either http1 or tcp based on the route protocol; this feature is only available if you turn it on in routing release

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,
      "protocol": "tcp"
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080,
      "protocol": "tcp"
    }
 ],
  "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

Admin
Space Developer
Space Supporter

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,
      "protocol": "tcp"
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080,
      "protocol": "tcp"
    }
 ],
  "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

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

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,
          "protocol": "http1"
        },
        {
          "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
          "app": {
            "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
            "process": {
              "type": "web"
            }
          },
          "weight": null,
          "port": 8080,
          "protocol": "http1"
        }
      ],
      "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
service_instance_guids list of strings Comma-delimited list of service instance guids to filter by
page integer Page to display; valid values are integers >= 1
per_page integer Number of results per page;
valid values are 1 through 5000
order_by string Value to sort by. Defaults to ascending; prepend with - to sort descending.
Valid values are created_at, updated_at
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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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,
          "protocol": "http1"
        },
        {
          "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
          "app": {
            "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
            "process": {
              "type": "web"
            }
          },
          "weight": null,
          "port": 8080,
          "protocol": "http1"
        }
      ],
      "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
Space Supporter

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,
      "protocol": "tcp"
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080,
      "protocol": "tcp"
    }
 ],
  "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

Admin
Space Developer
Space Supporter

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

Admin
Space Developer
Space Supporter

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

Lists shared spaces relationship (experimental)

Lists the spaces that the route has been shared to.

Example Request
curl "https://api.example.org/v3/routes/[guid]/relationships/shared_spaces" \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json"
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "guid": "space-one-guid" },
    { "guid": "space-two-guid" }
  ],
  "links": {
    "self": {
      "href":"http://api.example.com/v3/routes/[guid]/relationships/shared_spaces"
    }
  }
}

Definition

GET /v3/routes/:guid/relationships/shared_spaces

Permitted roles

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

Share a route with other spaces (experimental)

This endpoint shares the route with the specified spaces. This allows users with read and write access in both the route’s space and a shared space to bind a route to an app in the shared space. In order to share into a space the requesting user must have write permission in the target space.

Example Request
curl "https://api.example.org/v3/routes/[guid]/relationships/shared_spaces" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid": "space-one-guid" },
      { "guid": "space-two-guid" }
    ]
  }'
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "guid": "space-one-guid" },
    { "guid": "space-two-guid" }
  ],
  "links": {
    "self": {
      "href":"http://api.example.com/v3/routes/[guid]/relationships/shared_spaces"
    }
  }
}

Definition

POST /v3/routes/:guid/relationships/shared_spaces

Required parameters

Name Type Description
data to-many relationship Shared space relationships; each space will have this route shared to it

Permitted roles

Admin
Space Developer
Space Supporter

Unshare a route that was shared with another space (experimental)

Unshares a route that was shared with another space.

Example Request
curl "https://api.example.org/v3/routes/:guid/relationships/shared_spaces/[space_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json"
HTTP/1.1 204 No Content

Definition

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

Permitted roles

Admin
Space Developer
Space Supporter

Transfer ownership (experimental)

Transfers a the ownership of a route to a another space. Users must have write access for both spaces to perform this action. The original owning space will still retain access to the route as a shared space. To completely remove a space from a route, users will have to use unshare route.

Example Request
curl "https://api.example.org/v3/routes/:route-guid/relationships/space" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json"
  -d '{ "data": { "guid": "space-guid"} }'
Example Response
HTTP/1.1 204 No Content

Definition

PATCH /v3/routes/:route-guid/relationships/space

Permitted roles

Admin
Space Developer

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,
        "protocol": "http2"
      },
      {
        "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "weight": null,
        "port": 9000,
        "protocol": "http1"
      }
    ],
    "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

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

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,
        "protocol": "http1"
      }
    ]
  }'
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,
        "protocol": "http2"
      },
      {
        "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "weight": null,
        "port": 9000,
        "protocol": "http1"
      }
    ],
    "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

Admin
Space Developer
Space Supporter

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,
        "protocol": "http1"
      }
    ]
  }'
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,
      "protocol": "http2"
    },
    {
      "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
      "app": {
        "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
        "process": {
          "type": "api"
        }
      },
      "weight": 39,
      "port": 9000,
      "protocol": "http1"
    }
  ],
  "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

Admin
Space Developer
Space Supporter

Update a destination protocol for a route

Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]"
  -d '{"protocol: "http2"}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
  "app": {
    "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
    "process": {
      "type": "web"
    }
  },
  "weight": 61,
  "port": 8080,
  "protocol": "http2",
  "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"
    }
  }
}

This endpoint updates the protocol of a route destination (app, port and weight cannot be updated)

Definition

PATCH /v3/routes/:guid/destinations/:guid

Optional parameters

Name Type Description
protocol string or null Protocol the destination will use. Valid protocols are http1 or http2 if route protocol is http, tcp if route protocol is tcp. A null value will set it to either http1 or tcp based on the route protocol;

Permitted roles

Admin
Space Developer
Space Supporter

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

Admin
Space Developer
Space Supporter

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

Admin
Space Developer
Space Supporter

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

Role Notes
Admin
Admin Read-Only
Global Auditor
Space Developer Only space-scoped brokers
Space Supporter 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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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
Space Developer Only space-scoped brokers
Space Supporter Only space-scoped brokers
Other Will receive an empty list

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

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

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

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

Role Notes
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 fields parameter Allowed values
created_ats timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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

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

Role Notes
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 initial, in progress, succeeded, or failed
Note: The initial state indicates that no response from the service broker has been received yet.
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

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

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, including 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
guids list of strings Comma-delimited list of service instance guids 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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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

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

Role Notes
Admin
Space Developer Can only purge service instances from space-scoped brokers

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

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

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

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

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

Get permissions for a service instance

Example Request
curl "https://api.example.org/v3/service_instances/[guid]/permissions" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "read": true,
  "manage": false
}

Get the current user’s permissions for the given service instance. If a user can get a service instance then they can ‘read’ it. Users who can update a service instance can ‘manage’ it.

This endpoint’s primary purpose is to enable third-party service dashboards to determine the permissions of a given Cloud Foundry user that has authenticated with the dashboard via single sign-on (SSO). For more information, see the Cloud Foundry documentation on Dashboard Single Sign-On.

Definition

GET /v3/service_instances/:guid/permissions

Permitted roles

All Roles

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

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 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 initial, in progress, succeeded, or failed
Note: The initial state indicates that no response from the service broker has been received yet.
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

Role Notes
Admin
Space Developer
Space Supporter Only allowed to create bindings of type app.

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_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
Space Supporter

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

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

Role Notes
Admin
Space Developer
Space Supporter Only allowed to delete bindings of type app.

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_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
Space Supporter

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

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

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

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

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

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:

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

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

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

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

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

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

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

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

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

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

List users for a space

Example Request
curl "https://api.example.org/v3/spaces/:guid/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/spaces/:guid/users?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/spaces/:guid/users?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/spaces/:guid/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 with a role in the specified space.

Definition

GET /v3/spaces/:guid/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. Mutually exclusive with partial_usernames
partial_usernames list of strings Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with usernames
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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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
Space Supporter

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

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

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,
    "log_rate_limit_in_bytes_per_second": 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.log_rate_limit_in_bytes_per_second integer or null Total log rate limit allowed for all the started processes and running tasks in an organization
apps.per_app_tasks integer or null Maximum number of running tasks in a space
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,
    "log_rate_limit_in_bytes_per_second": 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.log_rate_limit_in_bytes_per_second integer or null Total log rate limit allowed for all the started processes and running tasks in an organization null (infinite)
apps.per_app_tasks integer or null Maximum number of running tasks in a space 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,
    "log_rate_limit_in_bytes_per_second": 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
Space Supporter 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,
        "log_rate_limit_in_bytes_per_second": 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,
        "log_rate_limit_in_bytes_per_second": 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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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,
      "log_rate_limit_in_bytes_per_second": 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,
    "log_rate_limit_in_bytes_per_second": 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.log_rate_limit_in_bytes_per_second integer or null Total log rate limit allowed for all the started processes and running tasks in an organization
apps.per_app_tasks integer or null Maximum number of running tasks in a space
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!",
   "build_rootfs_image": "my-stack",
   "run_rootfs_image": "my-stack",
   "default": true,
   "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
build_rootfs_image _string The name of the stack image associated with staging/building Apps. If a stack does not have unique images, this will be the same as the stack name.
run_rootfs_image _string The name of the stack image associated with running Apps + Tasks. If a stack does not have unique images, this will be the same as the stack name.
default boolean Whether the stack is configured to be the default stack for new applications.
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!",
   "build_rootfs_image": "my-stack",
   "run_rootfs_image": "my-stack",
   "default": true,
   "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!",
   "build_rootfs_image": "my-stack",
   "run_rootfs_image": "my-stack",
   "default": true,
   "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",
      "build_rootfs_image": "my-stack-1-build",
      "run_rootfs_image": "my-stack-1-run",
      "description": "This is my first stack!",
      "default": true,
      "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!",
      "build_rootfs_image": "my-stack-2-build",
      "run_rootfs_image": "my-stack-2-run",
      "default": false,
      "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 stack names to filter by
default boolean If true, only return the default stack
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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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 apps on a stack

Example Request
curl "https://api.example.org/v3/stacks/[guid]/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/stacks/[guid]/apps?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/stacks/[guid]/apps?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/stacks/[guid]/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": "cflinuxfs4"
          }
        },
        "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": "cflinuxfs4"
          }
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
            }
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/stacks/[guid]/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/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes"
          },
          "packages": {
            "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages"
          },
          "environment_variables": {
            "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables"
          },
          "current_droplet": {
            "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current"
          },
          "droplets": {
            "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets"
          },
          "tasks": {
            "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks"
          },
          "start": {
            "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start",
            "method": "POST"
          },
          "stop": {
            "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop",
            "method": "POST"
          },
          "revisions": {
            "href": "https://api.example.org//v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions"
          },
          "deployed_revisions": {
            "href": "https://api.example.org//v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed"
          },
          "features": {
            "href": "https://api.example.org//v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/features"
          }
        },
        "metadata": {
          "labels": {},
          "annotations": {}
        }
      }
    ]
  }

Retrieve all apps using a given stack.

Definition

GET /v3/stacks/:guid/apps

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, and name
label_selector string A query string containing a list of label selector requirements
created_ats timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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!",
   "build_rootfs_image": "my-stack",
   "run_rootfs_image": "my-stack",
   "default": true,
   "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,
  "log_rate_limit_in_bytes_per_second": 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
log_rate_limit_per_second integer Amount of log rate to allocate for the task in bytes
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,
  "log_rate_limit_in_bytes_per_second": 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
log_rate_limit_per_second[1] integer Amount of log rate to allocate for the task in bytes operator-configured default_app_log_rate_limit_in_bytes_per_second
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,
  "log_rate_limit_in_bytes_per_second": 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

Role Notes
Admin
Admin Read-Only
Global Auditor command field redacted
Org Manager command field redacted
Space Auditor command field redacted
Space Developer
Space Manager command field redacted
Space Supporter command field redacted

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,
      "log_rate_limit_in_bytes_per_second": 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,
      "log_rate_limit_in_bytes_per_second": 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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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,
      "log_rate_limit_in_bytes_per_second": 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,
      "log_rate_limit_in_bytes_per_second": 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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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 command field redacted
Org Manager command field redacted
Space Auditor command field redacted
Space Developer
Space Manager command field redacted
Space Supporter command field redacted

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,
  "log_rate_limit_in_bytes_per_second": 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,
  "log_rate_limit_in_bytes_per_second": 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
Space Supporter

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

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

Role Notes
Admin
Admin Read-Only
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
Space Supporter 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. Mutually exclusive with partial_usernames
partial_usernames list of strings Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with usernames
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 timestamp Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators
updated_ats 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 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
Space Supporter 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/:guid

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

Admin

Experimental Resources

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:

Start Diagram

  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.

Start Flow

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:cflinuxfs4" \
  -X GET \
  -H "Authorization: bearer [token]"
curl "https://api.example.org/v3/apps?names=dora,broker&stacks=cflinuxfs4" \
  -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

1 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

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

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

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:

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
Info Info Info in V3
Jobs Jobs
Organizations Organizations
Quota Definitions Organization Quotas Organization Quotas in V3
Resource Matches Resource Matches
Routes, Route Mappings Routes, Destinations 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:

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 “private” 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 “shared” if it doesn’t have this relationship.

Read more about the domain resource.

Info in V3

In V2, /v2/info provides descriptive information about the system and endpoints to external APIs.

In V3, /v3/info only provides descriptive information about the system.

To access the external APIs in V3, use the root (/).

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, destinations, and ports.

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_guids=guid.

GET /v2/spaces/:guid/services is now GET /v3/service_offerings?space_guids=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, those nested endpoints are carried over, but GET /v3/users is now available for all users in a similar way 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 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