Introduction

Overview

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

Running one-off tasks on Cloud Foundry
Applications consisting of several processes via a Procfile
Direct access to application packages and droplets
Changing application source code without stopping the app via deployments

Getting help

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

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

More resources

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

Concepts

API Resource

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

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

See Resources and Experimental Resources for specific resources.

Required fields

Example Person Resource

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

  "name": "Bob",

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

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

Links

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

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

The link object

Example Link object

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

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

Authentication

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

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

Use the CF CLI to obtain a bearer token: cf oauth-token

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

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

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

Resources with Fields

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

Fields Sample requests

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

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

Example response

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

Filters

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

Examples

Single value request

GET /v3/apps?names=the_name

This will return all apps with name the_name.

Multiple value request

GET /v3/apps?names=first_name,second_name

This will return all apps with name the_name OR second_name.

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

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

Exception

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

GET /v3/spaces?label_selector=production,east_coast

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

Combined filters

GET /v3/apps?names=the_name&stacks=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`, `cnb`, `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`

Cloud Native Buildpacks Lifecycle (experimental)

Example Cloud Native Buildpacks lifecycle

{
  "type": "cnb",
  "data": {
        "buildpacks": [
            "docker://example.org/java-buildpack:latest"
            "docker://second-example.org/logging-buildpack:latest"
        ],
        "stack": "cflinuxfs4",
        "credentials": {
            "example.org": {
                "username": "user",
                "password": "****"
            },
            "second-example.org": {
                "token": "****"
            },
        }
  }
}

This lifecycle allows Cloud Foundry to stage an application using the Cloud Native Buildpacks.

Note: the data.buildpacks field is required (at least 1 buildpack must be set).

Cloud Native Buildpacks lifecycle object

Name	Type	Description
type	string	`cnb`
data.buildpacks	list of strings	A list of URLs with either `docker://` or `http(s)://` scheme, pointing to the Cloud Native Buildpack OCI image. When the scheme is `http(s)://`, an OCI tarball is expected to be present at the specified location.
data.credentials	object	Credentials used to download the configured buildpacks. This can either contain username/password or a token.
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):

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

Annotation keys

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

An annotation key prefix must adhere to the following restrictions:

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

An annotation key name must adhere to the following restrictions:

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

Annotation values

Annotation values must adhere to the following restrictions:

Length: 0-5000 unicode characters

Labels and selectors

Example Resource with Labels

{
  "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
  "created_at": "2016-03-18T23:26:46Z",
  "updated_at": "2016-10-17T20:00:42Z",
  "name": "api-server",
  "metadata": {
    "labels": {
      "environment": "production",
      "internet-facing": "false"
    },
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}

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

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

Users could then find all sensitive apps with a selector for sensitive=true, resulting in a response containing only apps having the label key sensitive with a label value of 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):

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

Label keys

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

A label key prefix must adhere to the following restrictions:

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

A label key name must adhere to the following restrictions:

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

Label values

Label values must adhere to the following restrictions:

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

Selectors

Example label selector

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

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

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

Pagination

Example Paginated Response

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

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

The pagination object

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

Procfiles

Example Ruby Procfile

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

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

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

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

Procfile use cases

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

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

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

Web process

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

Specifying processes in manifest files

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

Query Parameters

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

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

Because commas are used to separate list entries, parameter values that contain commas must be percent-encoded. For example, to retrieve apps named either a,b or c,d, the 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"
      }
    },
    "current_droplet": {
      "data": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      }
    }
  },
  "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
relationships.current_droplet	to-one relationship	The current droplet used by the application
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"
      }
    },
    "current_droplet": {
      "data": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      }
    }
  },
  "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"
      }
    },
    "current_droplet": {
      "data": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      }
    }
  },
  "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"
            }
          },
          "current_droplet": {
            "data": {
              "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
            }
          }
        },
        "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"
            }
          },
          "droplet": {
            "data": {
              "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
            }
          }
        },
        "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`, `cnb`, `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"
      }
    },
    "current_droplet": {
      "data": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      }
    }
  },
  "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"
      }
    },
    "current_droplet": {
      "data": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      }
    }
  },
  "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"
      }
    },
    "current_droplet": {
      "data": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      }
    }
  },
  "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"
      }
    },
    "current_droplet": {
      "data": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      }
    }
  },
  "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

Clear buildpack cache for application

Example Request

curl "https://api.example.org/v3/apps/[guid]/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 the buildpack cache for a specified app. The buildpack cache is used during staging by buildpacks as a way to cache certain resources, e.g. downloaded Ruby gems. A user may want to use this endpoint when an app doesn’t stage anymore due to out-of-disk caused by a large buildpack cache content.

Definition

POST /v3/apps/:guid/actions/clear_buildpack_cache

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

audit.app.apply_manifest
audit.app.build.create
audit.app.copy-bits
audit.app.create
audit.app.delete-request
audit.app.deployment.cancel
audit.app.deployment.create
audit.app.deployment.continue
audit.app.droplet.create
audit.app.droplet.delete
audit.app.droplet.download
audit.app.droplet.mapped
audit.app.droplet.upload
audit.app.environment.show
audit.app.environment_variables.show
audit.app.map-route
audit.app.package.create
audit.app.package.delete
audit.app.package.download
audit.app.package.upload
audit.app.process.crash
audit.app.process.create
audit.app.process.delete
audit.app.process.ready
audit.app.process.not-ready
audit.app.process.rescheduling
audit.app.process.scale
audit.app.process.terminate_instance
audit.app.process.update
audit.app.restage
audit.app.restart
audit.app.revision.create
audit.app.revision.environment_variables.show
audit.app.ssh-authorized
audit.app.ssh-unauthorized
audit.app.start
audit.app.stop
audit.app.task.cancel
audit.app.task.create
audit.app.unmap-route
audit.app.update
audit.app.upload-bits

Organization lifecycle

audit.organization.create
audit.organization.delete-request
audit.organization.update

Route lifecycle

audit.route.create
audit.route.delete-request
audit.route.share
audit.route.transfer-owner
audit.route.unshare
audit.route.update

Service lifecycle

audit.service.create
audit.service.delete
audit.service.update

Service_binding lifecycle

audit.service_binding.create
audit.service_binding.delete
audit.service_binding.show
audit.service_binding.start_create
audit.service_binding.start_delete
audit.service_binding.update

Service_broker lifecycle

audit.service_broker.create
audit.service_broker.delete
audit.service_broker.update

Service_dashboard_client lifecycle

audit.service_dashboard_client.create
audit.service_dashboard_client.delete

Service_instance lifecycle

audit.service_instance.bind_route
audit.service_instance.create
audit.service_instance.delete
audit.service_instance.purge
audit.service_instance.share
audit.service_instance.show
audit.service_instance.start_create
audit.service_instance.start_delete
audit.service_instance.start_update
audit.service_instance.unbind_route
audit.service_instance.unshare
audit.service_instance.update

Service_key lifecycle

audit.service_key.create
audit.service_key.delete
audit.service_key.show
audit.service_key.start_create
audit.service_key.start_delete
audit.service_key.update

Service_plan lifecycle

audit.service_plan.create
audit.service_plan.delete
audit.service_plan.update

Service_plan_visibility lifecycle

audit.service_plan_visibility.create
audit.service_plan_visibility.delete
audit.service_plan_visibility.update

Service_route_binding lifecycle

audit.service_route_binding.create
audit.service_route_binding.delete
audit.service_route_binding.start_create
audit.service_route_binding.start_delete
audit.service_route_binding.update

Space lifecycle

audit.space.create
audit.space.delete-request
audit.space.update

User lifecycle

audit.user.organization_auditor_add
audit.user.organization_auditor_remove
audit.user.organization_billing_manager_add
audit.user.organization_billing_manager_remove
audit.user.organization_manager_add
audit.user.organization_manager_remove
audit.user.organization_user_add
audit.user.organization_user_remove
audit.user.space_auditor_add
audit.user.space_auditor_remove
audit.user.space_developer_add
audit.user.space_developer_remove
audit.user.space_manager_add
audit.user.space_manager_remove
audit.user.space_supporter_add
audit.user.space_supporter_remove

User_provided_service_instance lifecycle

audit.user_provided_service_instance.create
audit.user_provided_service_instance.delete
audit.user_provided_service_instance.show
audit.user_provided_service_instance.update

Special events

app.crash
blob.remove_orphan

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

Manage updating an app’s droplet directly after an application package is staged
Roll an app back to a specific revision along with its associated droplet

Deployments are different than the traditional method of pushing app updates which performs start/stop deployments.

Deployment strategies supported:

Rolling deployments allows for applications to be deployed without incurring downtime by gradually rolling out instances. Max-in-flight can be configured to specify how many instances are rolled out simultaneously.
Canary deployments deploy a single instance and pause for user evaluation. If the canary instance is deemed successful, the deployment can be resumed via the continue action. The deployment then continues like a rolling deployment. This feature is experimental and is subject to change.

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": "canary",
  "options" : {
    "max_in_flight": 3,
  },
  "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"
    }
    "continue": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue",
      "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` - `PAUSED` (only valid for canary deployments) - `CANCELING` 2. If status.value is `FINALIZED` - `DEPLOYED` - `CANCELED` - `SUPERSEDED` (another deployment created for app before completion)
status.details.last_successful_healthcheck	timestamp	Timestamp of the last successful healthcheck
status.details.last_status_change	timestamp	Timestamp of last change to status.value or status.reason
strategy	string	Strategy used for the deployment; supported strategies are `rolling` and `canary` (experimental)
options.max_in_flight	integer	The maximum number of new instances to deploy simultaneously
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": "canary",
  "options" : {
    "max_in_flight": 3,
  },
  "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"
    }
    "continue": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue",
      "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`
options.max_in_flight	integer	The maximum number of new instances to deploy simultaneously	1
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": "canary",
  "options" : {
    "max_in_flight": 3,
  },
  "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"
    }
    "continue": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue",
      "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",
      "options" : {
        "max_in_flight": 1,
      },
      "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`, `PAUSED`, `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": "canary",
  "options" : {
    "max_in_flight": 3,
  },
  "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"
    }
    "continue": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue",
      "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

Continue a deployment

Example Request

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

Example Response

HTTP/1.1 200 OK

Definition

POST /v3/deployments/:guid/actions/continue

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

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: `diego_cnb (experimental)` Default: `false` Description: When enabled, the staging process using Cloud Native Buildpacks is supported.
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`, or`FAILED`
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: "[email protected] [email protected]"
    labels:
      sensitive: true
  processes:
  - type: web
    command: start-web.sh
    disk_quota: 512M
    health-check-http-endpoint: /healthcheck
    health-check-type: http
    health-check-invocation-timeout: 10
    instances: 3
    memory: 500M
    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
lifecycle	string	Type of the lifecycle; valid values are `buildpack`, `cnb`, `docker`. Defaults to `buildpack`, unless the docker property is present.
buildpacks	list of strings	a) An empty array, which will automatically select the appropriate default buildpack according to the coding language (incompatible with lifecycle: cnb) 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_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

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

The process object

Example Process object

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "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`, `STOPPING`, `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