NAV Navbar

Introduction

Overview

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

Getting help

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

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

More resources

Concepts

API Resource

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

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

See Resources and Experimental Resources for specific resources.

Required fields

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

  "name": "Bob",

  "links": {
    "self": {
      "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}
Name Type Description
guid uuid The unique identifier for the resource
created_at datetime The ISO8601 compatible date and time when resource was created
updated_at datetime The ISO8601 compatible date and time when resource was last updated
links links object URLs to related resources and actions for the current resource

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

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

Example Link object
{
  "href": "http://example.com/some/endpoint",
  "method": "POST"
}
Name Type Description
href string The absolute URL
method string An optional field containing the HTTP method to be used when following the URL

Authentication

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

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

Authorization

Access to resources is determined by combining scopes in the OAuth 2 token with user roles that are managed by the API.

OAuth 2 scopes

Scope Description
cloud_controller.admin This scope provides read and write access to all resources
cloud_controller.admin_read_only This scope provides read only access to all resources
cloud_controller.global_auditor This scope provides read only access to all resources except secrets (such as environment variables)
cloud_controller.read This scope provides read access to resources based on user roles
cloud_controller.write This scope provides write access to resources based on user roles
cloud_controller.update_build_state This scope allows its bearer to update the state of a build; currently only used when updating builds

Cloud Foundry user roles

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

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

Component roles

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

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

Errors

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

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

The error object

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

Fields

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

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

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

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

Fields parameter

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

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

Resources with Fields

Resource Endpoint
Service Instances v3/service_instances, v3/service_instances/:guid
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. The available filter parameters are described in a resource’s “list” endpoint in the section “Query parameters”.

Examples

Single value request

GET /v3/apps?names=the_name

This will return all apps with name the_name.

Multiple value request

GET /v3/apps?names=first_name,second_name

This will return all apps with name the_name OR second_name.

Exception

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

GET /v3/spaces?label_selector=production,east_coast

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

Combined filters

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

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

Empty filters

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

GET /v3/buildpacks?stacks=

This will return all buildpacks with stack NULL.

GET /v3/routes?hosts=hostname1,,hostname2

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

Filtering on Inequalities (Experimental)

Certain fields can be filtered using inequality when listing resources.

For example, a response to /v3/audit_events?created_at[lt]=iso8601-timestamp will contain audit events with a created_at timestamp strictly earlier than iso8601-timestamp.

Currently, this is only supported on the created_at parameter.

Valid inequality 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
Resources with inequalities

The following resources can filter using inequality operators:

Include

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

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

Resources with includes

The following resources can take an include parameter:

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

Sample requests

Example request to apps resource to include parent orgs and spaces
curl "https://api.example.org/v3/apps?include=space.organization" \
  -X GET \
  -H "Authorization: bearer [token]"
Example response
{
   "pagination": {
     "total_results": 2,
     "...": "..."
   },
   "resources": [
      {
         "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
         "name": "app1",
         "...": "..."
      },
      {
         "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
         "name": "app2",
         "...": "..."
      }
   ],
   "included": {
      "spaces": [
         {
            "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
            "name": "space1",
            "...": "..."
         },
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space2",
            "...": "..."
         }
      ],
      "organizations": [
         {
            "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
            "name": "org1",
            "...": "..."
         },
         {
            "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
            "name": "org2",
            "...": "..."
         }
      ]
   }
}
Example request for a single app instance to include its parent space
curl "https://api.example.org/v3/apps/[guid]?include=space" \
  -X GET \
  -H "Authorization: bearer [token]"
Example response
{
   "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
   "name": "staticfile",
   "...": "..."
   "included": {
      "spaces": [
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space1a",
            "...": "..."
         }
      ]
   }
}

Lifecycles

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

The lifecycle object

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

Buildpack lifecycle

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

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

Buildpack lifecycle object

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

Docker lifecycle

Example Docker Lifecycle
{
  "type": "docker",
  "data": {}
}

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

Docker lifecycle object

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

Metadata

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

Annotations

Example Resource with Annotations
{
  "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
  "created_at": "2016-03-18T23:26:46Z",
  "updated_at": "2016-10-17T20:00:42Z",
  "name": "api-server",
  "metadata": {
    "labels": {},
    "annotations": {
      "contacts": "Bill tel(1111111) email(bill@fixme), Bob tel(222222) pager(3333333#555) email(bob@fixme)"
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}

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

Examples may include (but are not limited to):

Annotation keys

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

An annotation key prefix must adhere to the following restrictions:

An annotation key name must adhere to the following restrictions:

Annotation values

Annotation values must adhere to the following restrictions:

Labels and selectors

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

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

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

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

Labels

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

Examples may include (but are not limited to):

Label keys

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

A label key prefix must adhere to the following restrictions:

A label key name must adhere to the following restrictions:

Label values

Label values must adhere to the following restrictions:

Selectors

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

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

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

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

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

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

See the metadata documentation for more information.

Updating labels and annotations

Example Initial Metadata
{
  "metadata": {
    "labels": {
      "environment": "staging",
      "ready-to-deploy": "true"
    },
    "annotations": {
       "spring-version": "5.1",
       "app-version": "0.1-alpha"
     }
  }
}
Example Patch Request Body
{
  "metadata": {
    "labels": {
      "environment": "production",
      "ready-to-deploy": null
    },
    "annotations": {
       "app-version": "0.1",
       "deployed-month": "november"
     }
  }
}
Example Final Metadata
{
  "metadata": {
    "labels": {
      "environment": "production"
    },
    "annotations": {
       "spring-version": "5.1",
       "app-version": "0.1",
       "deployed-month": "november"
     }
  }
}

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

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

Pagination

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

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

The pagination object

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

Procfiles

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

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

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

Procfile use cases

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

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

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

Web process

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

Specifying processes in manifest files

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

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

Warnings

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

Warnings appear on the job resource.

The warning object

Name Type Description
detail string Description of the warning

Resources

Admin

These endpoints are only for admin users.

Clear buildpack cache

Example Request
curl "https://api.example.org/v3/admin/actions/clear_buildpack_cache" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

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

Definition

POST /v3/admin/actions/clear_buildpack_cache

Permitted Roles

Admin

Apps

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

The app object

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

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

Create an app

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

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

Definition

POST /v3/apps

Required parameters

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Get an app

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

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

Definition

GET /v3/apps/:guid

Query parameters

Name Type Description
include (experimental) string Optionally include additional related resources in the response; valid values are space and space.organization

Permitted roles

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

List apps

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

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

Retrieve all apps the user has access to.

Definition

GET /v3/apps

Query parameters

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

Permitted roles

All Roles

Update an app

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

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

Definition

PATCH /v3/apps/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Delete an app

Example Request
curl "https://api.example.org/v3/apps/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/apps/:guid

Permitted roles

Admin
Space Developer

Get current droplet

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

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

Definition

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

Permitted roles

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

Get current droplet association for an app

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

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

This endpoint retrieves the current droplet relationship for an app.

Definition

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

Permitted roles

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

Get environment for an app

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

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

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

Definition

GET /v3/apps/:guid/env

Permitted roles

Admin
Admin Read-Only
Space Developer

Get environment variables for an app

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

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

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

Definition

GET /v3/apps/:guid/environment_variables

Permitted roles

Admin
Admin Read-Only
Space Developer

Get permissions

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

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

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

Definition

GET /v3/apps/:guid/permissions

Permitted roles

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

Set current droplet

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

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

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

Definition

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

Permitted roles

Admin
Space Developer

Get SSH enabled for an app

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

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

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

Definition

GET /v3/apps/:guid/ssh_enabled

Permitted roles

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

Start an app

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

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

Definition

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

Permitted roles

Admin
Space Developer

Stop an app

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

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

Definition

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

Permitted roles

Admin
Space Developer

Update environment variables for an app

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

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

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

Definition

PATCH /v3/apps/:guid/environment_variables

Permitted roles

Admin
Space Developer

App Features

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

The app feature object

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

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

Supported app features

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

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

Get an app feature

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

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

Definition

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

Permitted roles

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

List app features

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

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

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

Definition

GET /v3/apps/:guid/features

Permitted roles

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

Update an app feature

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Space Developer

App Usage Events

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

Usage events are typically used by billing and chargeback applications.

The app usage event object

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

Name Type Description
guid uuid Unique identifier for the event
created_at datetime The time with zone when the event occurred
updated_at datetime 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

Permitted Roles

All Roles

Purge and seed app usage events

Example Request
curl "https://api.example.org/v3/app_usage_events/actions/destructively_purge_all_and_reseed" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

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

Definition

POST /v3/app_usage_events/actions/destructively_purge_all_and_reseed

Permitted Roles

Admin

Audit Events

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

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

The audit event object

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

Name Type Description
guid uuid Unique identifier for the event
created_at datetime The time with zone when the object was created
updated_at datetime The time with zone when the object was last updated
type string The type of the event
actor.guid string Unique identifier for the actor (user or system resource that performed the action)
actor.type string The actor type
actor.name string The name of the actor
target.guid uuid Unique identifier for the target (resource that the event acted upon)
target.type string The target type
target.name string The name of the target
data object Additional information about event
space.guid uuid Unique identifier for the space where the event occurred; if the event did not occur within a space, the space field will be null
organization.guid uuid Unique identifier for the organization where the event occurred; if the event did not occur within an organization, the organization field will be null
links links object Links to related resources

Get an audit event

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

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

Definition

GET /v3/audit_events/:guid

Permitted roles

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

List audit events

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

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

Retrieve all audit events the user has access to.

Definition

GET /v3/audit_events

Query parameters

Name Type Description
created_at iso8601 timestamp Timestamp to filter by. Only supports inequality operators, see valid comparison operators
types list of strings Comma-delimited list of event types to filter by
target_guids list of strings Comma-delimited list of target guids to filter by
space_guids list of strings Comma-delimited list of space guids to filter by
organization_guids list of strings Comma-delimited list of organization guids to filter by
page integer Page to display; valid values are integers >= 1
per_page integer Number of results per page;
valid values are 1 through 5000
order_by string Value to sort by. Defaults to ascending; prepend with - to sort descending.
Valid values are created_at, updated_at

Permitted roles

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

Builds

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

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

The build object

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

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

Create a build

Example Request
curl "https://api.example.org/v3/builds" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "package": {
       "guid": "[package-guid]"
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

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

Definition

POST /v3/builds

Required parameters

Name Type Description
package object App package to stage

Optional parameters

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

Permitted roles

Admin
Space Developer

Get a build

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

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

Definition

GET /v3/builds/:guid

Permitted roles

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

List builds

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

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

Retrieve all builds the user has access to.

Definition

GET /v3/builds

Query parameters

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

Permitted roles

All Roles

List builds for an app

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

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

Retrieve all builds for the app.

Definition

GET /v3/apps/:guid/builds

Query parameters

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

Permitted roles

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

Update a build

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

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

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

Definition

PATCH /v3/builds/:guid

Optional parameters

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

Permitted roles

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

Buildpacks

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

The buildpack object

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

Name Type Description
guid uuid Unique identifier for the buildpack
created_at datetime The time with zone when the object was created
updated_at datetime The time with zone when the object was last updated
name string The name of the buildpack; to be used by app buildpack field (only alphanumeric characters)
state string The state of the buildpack Valid value is: AWAITING_UPLOAD
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 (experimental) string A query string containing a list of label selector requirements

Permitted roles

All Roles

Update a buildpack

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

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

Definition

PATCH /v3/buildpacks/:guid

Optional parameters

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

Permitted roles

Admin

Delete a buildpack

Example Request
curl "https://api.example.org/v3/buildpacks/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/buildpacks/:guid

Permitted Roles

Admin

Upload buildpack bits

Example Request
curl "https://api.example.org/v3/buildpacks/[guid]/upload" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -F bits=@"buildpack.zip"
Example Response
HTTP/1.1 202 OK
Content-Type: application/json
Location: https://api.example.org/v3/jobs/[guid]

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

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

Definition

POST /v3/buildpacks/:guid/upload

Required parameters

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

Permitted roles

Admin

Deployments

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

They can either:

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

The deployment object

Example Deployment object

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

Name Type Description
guid uuid Unique identifier for the deployment
created_at datetime The time with zone when the object was created
updated_at datetime The time with zone when the object was last updated
state string (deprecated) This field will be removed in the future; use the status fields to determine deployment state instead
status.value string The current status of the deployment; valid values are ACTIVE (meaning in progress) and FINALIZED (meaning finished, either successfully or not)
status.reason string The reason for the status of the deployment;
following list represents valid values:
1. If status.value is ACTIVE
- DEPLOYING
- CANCELING
2. If status.value is FINALIZED
- DEPLOYED
- CANCELED
- SUPERSEDED (another deployment created for app before completion)
- DEGENERATE (the deployment was created incorrectly by the system)
status.details object The details for the status of the deployment shows a timestamp of the last successful healthcheck
strategy string Strategy used for the deployment; supported strategies are rolling only
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",
  "state": "DEPLOYING",
  "status": {
    "value": "ACTIVE",
    "reason": "DEPLOYING",
    "details": {
      "last_successful_healthcheck": "2018-04-25T22:42:10Z"
    }
  },
  "strategy": "rolling",
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
    }
  }
}

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

Definition

POST /v3/deployments

Required parameters

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

Optional parameters

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

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

Permitted roles

Admin
Space Developer

Get a deployment

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


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

Definition

GET /v3/deployments/:guid

Permitted roles

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

List deployments

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

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

Retrieve all deployments the user has access to.

Definition

GET /v3/deployments

Query parameters

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

Permitted roles

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

Update a deployment

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

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


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

Definition

PATCH /v3/deployments/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Cancel a deployment

Example Request
curl "https://api.example.org/v3/deployments/[guid]/actions/cancel" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK

Definition

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

Permitted roles

Admin
Space Developer

Domains

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

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

The domain object

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

Name Type Description
guid uuid Unique identifier for the domain
created_at datetime The time with zone when the object was created
updated_at datetime The time with zone when the object was last updated
name string The name of the domain;
must be between 3 ~ 253 characters and follow RFC 1035
internal boolean Whether the domain is used for internal (container-to-container) traffic
router_group.guid uuid The guid of the desired router group to route tcp traffic through; if set, the domain will only be available for tcp traffic
supported_protocols list of strings Available protocols for routes using the domain, currently http and tcp
relationships.organization to-one relationship The organization the domain is scoped to; if set, the domain will only be available in that organization; otherwise, the domain will be globally available
relationships.shared_organizations to-many relationship Organizations the domain is shared with; if set, the domain will be available in these organizations in addition to the organization the domain is scoped to
metadata.labels label object Labels applied to the domain
metadata.annotations annotation object Annotations applied to the domain
links links object Links to related resources

Create a domain

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

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

Definition

POST /v3/domains

Required parameters

Name Type Description
name string Name of the domain

Optional parameters

Name Type Description Default
internal boolean Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic false
router_group.guid uuid The desired router group guid.
note: creates a tcp domain; cannot be used when internal is set to true or domain is scoped to an org
null
organization to-one relationship A relationship to the organization the domain will be scoped to;
note: cannot be used when internal is set to true or domain is associated with a router group
shared_organizations to-many relationship A relationship to organizations the domain will be shared with
Note: cannot be used without an organization relationship
metadata.labels label object Labels applied to the domain
metadata.annotations annotation object Annotations applied to the domain

Permitted roles

Role Notes
Admin
Org Manager When an organization relationship is provided

Get a domain

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

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

Definition

GET /v3/domains/:guid

Permitted roles

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

List domains

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

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

Retrieve all domains the user has access to.

Definition

GET /v3/domains

Query parameters

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

Permitted roles

All Roles

List domains for an organization

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/domains?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/domains?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/domains?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "name": "test-domain.com",
      "internal": false,
      "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.

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 (experimental) string A query string containing a list of label selector requirements

Permitted roles

All Roles

Update a domain

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

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

Definition

PATCH /v3/domains/:guid

Optional parameters

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

Permitted roles

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

Delete a domain

Example Request
curl "https://api.example.org/v3/domains/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/domains/:guid

Permitted roles

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

Share a domain

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

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

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

Definition

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

Required parameters

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

Permitted roles

Role Notes
Admin
Org Manager

Unshare a domain

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

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

Definition

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

Permitted roles

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

Droplets

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

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

The droplet object

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

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

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

Buildpack droplet

Name Type Description
checksum.type string Hashing algorithm for checksum; supported algorithms are sha256 and sha1
checksum.value string Checksum of droplet
buildpacks array of detected buildpack objects Detected buildpacks from the staging process
stack string The root filesystem to use with the buildpack, for example cflinuxfs3
Detected buildpack object
Name Type Description
name string System buildpack name
detect_output string Output during buildpack detect process
buildpack_name string Name reported by the buildpack
version string Version reported by the buildpack

Docker droplet

Name Type Description
image string Docker image name

Create a droplet

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

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

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

Definition

POST /v3/droplets

Required parameters

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Get a droplet

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

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

Definition

GET /v3/droplets/:guid

Permitted roles

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

List droplets

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

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

Retrieve all droplets the user has access to.

Definition

GET /v3/droplets

Query parameters

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

Permitted roles

All Roles

List droplets for a package

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

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {}
      },
      "image": null,
      "execution_metadata": "PRIVATE DATA HIDDEN",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "checksum": {
        "type": "sha256",
        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "buildpacks": [
        {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14",
          "version": "1.1.1.",
          "buildpack_name": "ruby"
        }
      ],
      "stack": "cflinuxfs3",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "relationships": {
        "app": {
          "data": {
            "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
          "method": "PATCH"
        },
        "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 (experimental) string A query string containing a list of label selector requirements

Permitted roles

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

List droplets for an app

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

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

Retrieve a list of droplets belonging to an app.

Definition

GET /v3/apps/:guid/droplets

Query parameters

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

Permitted roles

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

Update a droplet

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

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

Definition

PATCH /v3/droplets/:guid

Optional parameters

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

Permitted roles

Admin
Org Manager
Space Developer
Space Manager

Delete a droplet

Example Request
curl "https://api.example.org/v3/droplets/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/droplets/:guid

Permitted Roles

Admin
Space Developer

Copy a droplet

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

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

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

Definition

POST /v3/droplets?source_guid=:guid

Required query parameters

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

Required parameters

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

Permitted roles

Admin
Space Developer

Download droplet bits

Example Request
curl "https://api.example.org/v3/droplets/[guid]/download" \
  -X GET \
  -H "Authorization: bearer [token]" \
Example Response
HTTP/1.1 302 FOUND
Content-Type: application/json

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

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

Definition

POST /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 datetime The time with zone when the object was last updated; this will be blank for feature flags that have not been configured
custom_error_message string The error string returned by the API when a client performs an action disabled by the feature flag
links links object Links to related resources

List of feature flags

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

Get a feature flag

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

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

Definition

GET /v3/feature_flags/:name

Permitted roles

All Roles

List feature flags

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

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

Retrieve all feature_flags.

Definition

GET /v3/feature_flags

Query parameters

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

Permitted roles

All Roles

Update a feature flag

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

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

Definition

PATCH /v3/feature_flags/:name

Optional parameters

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

Permitted roles

Admin

Info

Info endpoints expose Cloud Controller configuration information.

Get platform info

Example Request
curl "https://api.example.org/v3/info" \
  -X GET
Example Response with configured values
HTTP/1.1 200 OK
Content-Type: application/json

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

Example Response with unconfigured values
HTTP/1.1 200 OK
Content-Type: application/json

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

Definition

GET /v3/info

Authentication

No authentication required.

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

Create an isolation segment

Example Request
curl "https://api.example.org/v3/isolation_segments" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_segment"
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

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

Definition

POST /v3/isolation_segments

Required parameters

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

Permitted roles

Admin

Get an isolation segment

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

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

Definition

GET /v3/isolation_segments/:guid

Permitted roles

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

List isolation segments

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

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

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

Definition

GET /v3/isolation_segments

Query parameters

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

Permitted roles

All Roles

List organizations relationship

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

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

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

Definition

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

Permitted roles

All Roles

List spaces relationship

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

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

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

Definition

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

Permitted roles

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

Update an isolation segment

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

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

Definition

PATCH /v3/isolation_segments/:guid

Optional parameters

Name Type Description
name string Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness
metadata.labels 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 datetime The time with zone when the object was created
updated_at datetime The time with zone when the object was last updated
operation string Current desired operation of the job on a model
state string State of the job; valid values are PROCESSING, POLLING, COMPLETE, orFAILED
errors errors list Array of errors that occurred while processing the job
warnings warnings list Array of warnings that occurred while processing the job
links links object Links to related resources

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

Get a job

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

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

Failed Job Example Response
HTTP/1.1 200 OK
Content-Type: application/json

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

Definition

GET /v3/jobs/:guid

Permitted roles

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

Manifests

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

The manifest schema

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

  - name: upcaser
    process_types: [ 'worker' ]
    command: ./tr-server
    memory: 2G

Space-level configuration

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

App-level configuration

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

Name Type Description
name string Name of the app
buildpacks array of strings a) An empty array, which will automatically select the appropriate default buildpack according to the coding language
b) An array of one or more URLs pointing to buildpacks
c) An array of one or more installed buildpack names
Replaces the legacy buildpack field
docker object If present, the created app will have Docker lifecycle type; the value of this key is ignored by the API but may be used by clients to source the registry address of the image and credentials, if needed; the generate manifest endpoint will return the registry address of the image and username provided with this key
env object A key-value mapping of environment variables to be used for the app when running
no-route boolean When set to true, any routes specified with the routes attribute will be ignored and any existing routes will be removed
processes array of process configurations List of configurations for individual process types
random-route boolean Creates a random route for the app if true; if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored regardless of its value
default-route boolean If true, a route for the app will be created using the app name as the hostname and the containing organization’s default domain as the domain; if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored regardless of its value
routes array of route objects List declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist; example route object: - route: www.examplecom/path
services array of service configurations A list of service-instances to bind to the app
sidecars array of sidecar configurations A list of configurations for individual sidecars
stack string The root filesystem to use with the buildpack, for example cflinuxfs3
metadata.labels label object Labels applied to the app
metadata.annotations annotation object Annotations applied to the app
buildpack string DEPRECATED in favor of the buildpacks field above

Process-level configuration

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

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

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

Service-level configuration

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

Name Type Description
name string (Required) The name of the service instance to be bound to
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 array of strings List of processes to associate sidecar with
memory integer Memory in MB that the sidecar will be allocated

Apply a manifest to a space

Example Request
curl "https://api.example.org/v3/spaces/[guid]/actions/apply_manifest" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/x-yaml" \
  --data-binary @/path/to/manifest.yml
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Apply changes specified in a manifest to the named apps and their underlying processes. The apps must reside in the space. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.

Definition

POST /v3/spaces/:guid/actions/apply_manifest

Permitted roles

Admin
Space Developer

Generate a manifest for an app

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

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

Generate a manifest for an app and its underlying processes.

Definition

GET /v3/apps/:guid/manifest

Permitted Roles

Admin
Admin Read-Only
Space Developer

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 datetime The time with zone when the object was created
updated_at datetime The time with zone when the object was last updated
name string 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 (experimental) string A query string containing a list of label selector requirements

Permitted roles

All Roles

List organizations for isolation segment

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

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

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

Definition

GET /v3/isolation_segments/:guid/organizations

Query parameters

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

Permitted roles

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

Update an organization

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

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

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

Definition

PATCH /v3/organizations/:guid

Optional parameters

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

Permitted roles

Admin
Org Manager

Delete an organization

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

Example Request
curl "https://api.example.org/v3/organizations/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/organizations/:guid

Permitted roles

Role Notes
Admin

Assign default isolation segment

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

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

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

Definition

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

Required parameters

Name Type Description
data to-one relationship Isolation segment relationship; apps will run in this isolation segment; set data to null to remove the relationship

Permitted roles

Admin
Org Manager

Get default isolation segment

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

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

Retrieve the default isolation segment for a given organization.

Definition

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

Permitted roles

All Roles

Get default domain

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

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

Retrieve the default domain for a given organization.

Definition

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

Permitted roles

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

Get usage summary

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

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

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

Definition

GET /v3/organizations/:guid/usage_summary

Permitted roles

All Roles

Organization Quotas

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

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

For more information, see the Cloud Foundry docs.

The organization quota object

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

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

Create an organization quota

Example Request
curl "https://api.example.org/v3/organization_quotas" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
        "name": "production"
      }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

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

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

To create an organization quota you must be an admin.

Definition

POST /v3/organization_quotas

Required parameters

Name Type Description
name string Name of the quota

Optional parameters

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

Permitted roles

Role Notes
Admin

Get an organization quota

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

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

This endpoint gets an individual organization quota resource.

Definition

GET /v3/organization_quotas/:guid

Permitted roles

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

List organization quotas

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

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

This endpoint lists all organization quota resources.

Definition

GET /v3/organization_quotas

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

Permitted roles

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

Apply an organization quota to an organization

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

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

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

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

Definition

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

Required parameters

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

Permitted roles

Role Notes
Admin

Delete an organization quota

Organization quotas cannot be deleted when applied to any organizations.

Example Request
curl "https://api.example.org/v3/organizations_quotas/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/organization_quotas/:guid

Permitted roles

Role Notes
Admin

Update an organization quota

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

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

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

Definition

PATCH /v3/organization_quotas/:guid

Optional parameters

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

Permitted roles

Role Notes
Admin

Packages

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

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

The package object

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

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

Bits package data

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

Name Type Description
data.error string If an error occurs this field will contain the error message
data.checksum.type string The checksum type, for example: sha256
data.checksum.value string The checksum value; this will be populated after bits are uploaded

Docker package data

A Docker package references a Docker image from a registry.

Name Type Description
data.image string The registry address of the image
data.username string The username for the image’s registry
data.password string The password for the image’s registry

Create a package

Example Request (buildpack app)
curl "https://api.example.org/v3/packages" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "bits",
    "relationships": {
      "app": {
        "data": {
          "guid": "[guid]"
        }
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

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

Example Request (Docker app)
curl "https://api.example.org/v3/packages" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "docker",
    "relationships": {
      "app": {
        "data": {
          "guid": "[guid]"
        }
      }
    },
    "data": {
      "image": "registry/image:latest",
      "username": "username",
      "password": "password"
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

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

Definition

POST /v3/packages

Required parameters

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

Optional parameters

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

Conditional Parameters

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

Permitted roles

Admin
Space Developer

Get a package

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

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

Definition

GET /v3/packages/:guid

Permitted roles

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

List packages

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

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

Retrieve all packages the user has access to.

Definition

GET /v3/packages

Query parameters

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

Permitted roles

All Roles

List packages for an app

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

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

Definition

GET /v3/apps/:guid/packages

Query parameters

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

Permitted roles

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

Update a package

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

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

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

Definition

PATCH /v3/packages/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Delete a package

Example Request
curl "https://api.example.org/v3/packages/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/packages/:guid

Permitted Roles

Admin
Space Developer

Copy a package

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

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

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

Definition

POST /v3/packages?source_guid=:guid

Required query parameters

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

Required parameters

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

Permitted roles

Admin
Space Developer

Download package bits

Example Request
curl "https://api.example.org/v3/packages/[guid]/download" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 302 Found

You are being redirected.

This endpoint downloads the bits of an existing package.

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

Definition

GET /v3/packages/:guid/download

Permitted roles

Admin
Space Developer

Stage a package

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

Upload package bits

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

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

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

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

Definition

POST /v3/packages/:guid/upload

Optional parameters

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

Permitted roles

Admin
Space Developer

Processes

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

Web process type

The process object

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

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

The health check object

Example health check object
{
  "type": "port",
  "data": {
    "timeout": null
  }
}

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

The process stats object

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

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

Get a process

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

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

Definition

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

Permitted roles

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

Get stats for a process

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

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

Definition

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

Permitted roles

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

List processes

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

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

Retrieve all processes the user has access to.

Definition

GET /v3/processes

Query parameters

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

Permitted roles

All Roles

List processes for app

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

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

Retrieves all processes belonging to an app.

Definition

GET /v3/apps/:guid/processes

Query parameters

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

Permitted roles

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

Update a process

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

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

Definition

PATCH /v3/processes/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Scale a process

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

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

Definition

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Terminate a process instance

Example Request
curl "https://api.example.org/v3/processes/[guid]/instances/[index]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

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

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

Definition

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

Permitted Roles

Admin
Space Developer

Resource Matches

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

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

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

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

The resource match object

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

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

Create a resource match

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

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

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

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

Definition

POST /v3/resource_matches

Required parameters

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

Permitted roles

All Roles

Roles

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

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

The role object

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

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

Valid role types

Create a role

Example Request (by user guid)
curl "https://api.example.org/v3/roles" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
      "type": "organization_auditor",
      "relationships": {
        "user": {
          "data": {
            "guid": "user-guid"
          }
        },
        "organization": {
          "data": {
            "guid": "org-guid"
          }
        }
      }
    }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

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

Example Request (by username and origin)
curl "https://api.example.org/v3/roles" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
      "type": "organization_auditor",
      "relationships": {
        "user": {
          "data": {
            "username": "user-name",
            "origin": "ldap"
          }
        },
        "organization": {
          "data": {
            "guid": "org-guid"
          }
        }
      }
    }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

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

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

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

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

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

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

Definition

POST /v3/roles

Required parameters

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

Permitted roles

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

Get a role

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

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

This endpoint gets an individual role resource.

Definition

GET /v3/roles/:guid

Query parameters

Name Type Description
include (experimental) list of strings Optionally include a list of unique related resources in the response;
valid values are user, space, and organization

Permitted roles

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

List roles

Example Request
curl "https://api.example.org/v3/roles" \
  -X GET \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json"
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

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

This endpoint lists roles that the user has access to.

Definition

GET /v3/roles

Query parameters

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

Permitted roles

All Roles

Delete a role

This endpoint deletes an individual role.

Example Request
curl "https://api.example.org/v3/roles/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/roles/:guid

Permitted roles

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

Routes

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

The route object

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

Name Type Description
guid uuid Unique identifier for the route
created_at datetime The time with zone when the object was created
updated_at datetime The time with zone when the object was last updated
protocol string The protocol supported by the route, based on the route’s domain configuration. Valid protocols are http and tcp
host string The hostname for the route; not compatible with routes specifying the tcp protocol;
must be under 63 characters long and only contain letters, numbers, dashes (-) or underscores(_)
path string The path for the route; not compatible with routes specifying the tcp protocol;
must be under 128 characters long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from RFC 2396
port integer or null The port that the route listens on. Only compatible with routes specifying the tcp protocol
url string The URL for the route; URLs of protocol http are a combination of host, domain name, and path; URLs of protocol tcp are a combination of domain name and port
destinations array of destination objects List of destinations for the route
relationships.space to-one relationship A relationship to the space containing the route. Routes can only be mapped to destinations in that space
relationships.domain to-one relationship A relationship to the domain of the route
metadata.labels label object Labels applied to the route
metadata.annotations annotation object Annotations applied to the route
links links object Links to related resources

The destination object

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

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

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

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

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

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

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

Create a route

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

{
  "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
  "protocol": "tcp",
  "port": 6666,
  "created_at": "2019-05-10T17:17:48Z",
  "updated_at": "2019-05-10T17:17:48Z",
  "host": "a-hostname",
  "path": "/some_path",
  "url": "a-hostname.a-domain.com/some_path",
  "destinations": [
    {
      "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
      "app": {
        "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    },
    {
      "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
      "app": {
        "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
        "process": {
          "type": "web"
        }
      },
      "weight": null,
      "port": 8080
    }
 ],
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "relationships": {
    "space":