NAV Navbar

Introduction

Overview

Welcome to the Cloud Foundry V3 API docs! Version 3 will add 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": "GET"
}
Name Type Description
href string The absolute URL.
method string An optional field containing the HTTP method to be used when following the URL.

Authentication

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

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

Authorization

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

OAuth2 scopes

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

Cloud Foundry user roles

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

Errors

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

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

The error object

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

Filters

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

Examples

Single value request

GET /v3/apps?names=the_name

This will return all apps with name the_name.

Multiple value request

GET /v3/apps?names=first_name,second_name

This will return all apps with name the_name OR second_name.

Multiple value request #2

GET /v3/spaces?label_selector=production,east_coast

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

Combined filters

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

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

Empty filters

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

GET /v3/buildpacks?stacks=

This will return all buildpacks with stack NULL.

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

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

Include

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

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

Resources with includes

The following resources can take an include parameter:

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

Sample requests

Example request to apps resource to include parent orgs and spaces
curl "https://api.example.org/v3/apps?include=space.organization" \
  -X GET \
  -H "Authorization: bearer [token]"
Example response
{
   "pagination": {
      "total_results": 2
      // rest of pagination omitted
   },
   "resources": [
      {
         "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
         "name": "app1"
         // rest omitted
      },
      {
         "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
         "name": "app2"
         // rest omitted
      }
   ],
   "included": {
      "spaces": [
         {
            "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
            "name": "space1"
            // rest of info on space1 omitted
         },
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space2"
            // rest of info on space2 omitted
         }
      ],
      "organizations": [
         {
            "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
            "name": "org1"
            // rest of info on org1 omitted
         },
         {
            "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
            "name": "org2"
            // rest of info on org2 omitted
         }
      ]
   }
}
Example request for a single app instance to include its parent space
curl "https://api.example.org/v3/apps/[guid]?include=space" \
  -X GET \
  -H "Authorization: bearer [token]"
Example response
{
   "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
   "name": "staticfile",
   // ...
   "included": {
      "spaces": [
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space1a"
           // ...
         }
      ]
   }
}
Example request for all spaces including their parent organizations
curl "https://api.example.org/v3/spaces?include=organization" \
  -X GET \
  -H "Authorization: bearer [token]"
    Example Response
{
   "pagination": {
      "total_results": 4,
      "total_pages": 1,
     // ...
   },
   "resources": [
      {
         "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
         "name": "space"
         // ...
      },
      {
         "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
         "name": "space1a"
        // ...
      },
      {
         "guid": "615e724a-dfae-4846-836b-8c413f6192cd",
         "name": "space1b"
         // ...
      },
      {
         "guid": "5801b8dd-5ca6-41bb-ba23-690e703c631a",
         "name": "space2a"
        // ...
      }
   ],
   "included": {
      "organizations": [
         {
            "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
            "name": "org"
            // ...
         },
         {
            "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
            "name": "org1"
            // ...
         },
         {
            "guid": "c4bf7e09-57e7-453c-8b8e-fbebc986201e",
            "name": "org2"
            // ...
         }
      ]
   }
}

Lifecycles

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

The lifecycle object

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

Buildpack lifecycle

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

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

Buildpack lifecycle object

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

Docker lifecycle

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

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

Docker lifecycle object

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

Metadata

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

Annotations

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

  "name": "api-server",

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

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

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

Examples may include (but are not limited to):

Annotation key

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

A annotation key prefix must adhere to the following restrictions:

A annotation key name must adhere to the following restrictions:

Annotation value

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.

Relationships

Relationships represent associations between resources. They can be used to create, read, update, and delete these associations. For example, an app has a relationship to a space (every app belongs in one space); a space has a relationship with an organization (every space belongs in one organization).

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

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

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

The relationship object

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

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

To-one relationships

Example to-one relationship
{
  "data": {
    "guid": "[related-resource-guid]"
  }
}

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

To-one relationship object

Name Type Description
data relationship object A single relationship
Setting the to-one relationship while creating an object
curl "https://api.example.org/v3/books" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "color": "yellow",
    "relationships": {
      "publisher": {
        "data": {
          "guid": "publisher-guid"
        }
      }
    }
  }'
Modifying the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": {
      "guid": "publisher-guid"
    }
  }'
Removing the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "data": null }'
Viewing the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X GET \
  -H "Authorization: bearer [token]"

To-many relationships

Example to-many relationship
{
  "data": [
    { "guid": "[related-resource-guid-1]" },
    { "guid": "[related-resource-guid-2]" }
  ]
}

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

To-many relationship object

Name Type Description
data array of relationship objects An array of multiple relationships.
Adding related to-many resources
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"author-guid-1" },
      { "guid":"author-guid-2" }
    ]
  }'
Replacing all to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"author-guid-3" },
      { "guid":"author-guid-4" }
    ]
  }'
Removing all to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "data": [] }'
Removing specific to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors/[author-guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Viewing the to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X GET \
  -H "Authorization: bearer [token]"

Status Codes

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

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

Resources

Apps

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

The app object

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

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

Create an app

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

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

Definition

POST /v3/apps

Required parameters

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Get an app

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

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

Definition

GET /v3/apps/:guid

Query parameters

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

Permitted roles

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

List apps

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

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

Retrieve all apps the user has access to.

Definition

GET /v3/apps

Query parameters

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

Permitted roles

All Roles

Update an app

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

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

Definition

PATCH /v3/apps/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Delete an app

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

Definition

DELETE /v3/apps/:guid

Permitted roles

Admin
Space Developer

Get current droplet

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

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

Definition

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

Permitted roles

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

Get current droplet association for an app

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

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

This endpoint retrieves the current droplet relationship for an app.

Definition

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

Permitted roles

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

Get environment for an app

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

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

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

Definition

GET /v3/apps/:guid/env

Permitted roles

Admin
Admin Read-Only
Space Developer

Get environment variables for an app

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

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

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

Definition

GET /v3/apps/:guid/environment_variables

Permitted roles

Admin
Admin Read-Only
Space Developer

Set current droplet

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

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

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

Definition

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

Permitted roles

Admin
Space Developer

Get SSH enabled for an app

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

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

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

Definition

GET /v3/apps/:guid/ssh_enabled

Permitted roles

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

Start an app

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

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

Definition

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

Permitted roles

Admin
Space Developer

Stop an app

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

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

Definition

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

Permitted roles

Admin
Space Developer

Update environment variables for an app

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

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

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

Definition

PATCH /v3/apps/:guid/environment_variables

Permitted roles

Admin
Space Developer

App Features

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

The app feature object

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

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

Supported app features

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

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

Get an app feature

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

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

Definition

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

Permitted roles

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

List app features

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

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

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

Definition

GET /v3/apps/:guid/features

Permitted roles

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

Update an app feature

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Space Developer

Audit Events

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

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

The audit event object

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

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

Get an audit event

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

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

Definition

GET /v3/audit_events/:guid

Permitted roles

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

List audit events

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

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

Retrieve all audit events the user has access to.

Definition

GET /v3/audit_events

Query parameters

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

Permitted roles

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

Builds

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

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

The build object

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

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

Create a build

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

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

Definition

POST /v3/builds

Required parameters

Name Type Description
package object App package to stage.

Optional parameters

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

Permitted roles

Admin
Space Developer

Get a build

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

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

Definition

GET /v3/builds/:guid

Permitted roles

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

List builds

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

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

Retrieve all builds the user has access to.

Definition

GET /v3/builds

Query parameters

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

Permitted roles

All Roles

List builds for an app

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

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

Retrieve all builds for the app.

Definition

GET /v3/apps/:guid/builds

Query parameters

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

Permitted roles

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

Update a build

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

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

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

Definition

PATCH /v3/builds/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Special Permitted roles **

Admin
Space Developer
Build State Updater

Buildpacks

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

The buildpack object

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

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

Create a buildpack

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

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

Definition

POST /v3/buildpacks

Required parameters

Name Type Description
name string Name of the buildpack.

Optional parameters

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

Permitted roles

Admin

Get a buildpack

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

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

Definition

GET /v3/buildpacks/:guid

Permitted roles

All Roles

List buildpacks

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

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

Retrieve all buildpacks the user has access to.

Definition

GET /v3/buildpacks

Query parameters

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

Permitted roles

All Roles

Update a buildpack

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

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

Definition

PATCH /v3/buildpacks/:guid

Optional parameters

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

Permitted roles

Admin

Delete a buildpack

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

Definition

DELETE /v3/buildpacks/:guid

Permitted Roles

Admin

Upload buildpack bits

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

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

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

Definition

POST /v3/buildpacks/:guid/upload

Required parameters

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

Permitted roles

Admin

Deployments

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

They can either:

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

The deployment object

Example Deployment object

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

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

Create a deployment

Example Request with Droplet
curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "droplet": {
    "guid": "[droplet-guid]"
  },
  "strategy": "rolling",
  "relationships": {
    "app": {
      "data": {
        "guid": "[app-guid]"
      }
    }
  }
}'
Example Request with Revision
curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "revision": {
    "guid": "[revision-guid]"
  },
  "strategy": "rolling",
  "relationships": {
    "app": {
      "data": {
        "guid": "[app-guid]"
      }
    }
  }
}'
Example Response
HTTP/1.1 201 OK
Content-Type: application/json


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

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

Definition

POST /v3/deployments

Required parameters

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

Optional parameters

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

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

Permitted roles

Admin
Space Developer

Get a deployment

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


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

Definition

GET /v3/deployments/:guid

Permitted roles

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

List deployments

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

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

Retrieve all deployments the user has access to.

Definition

GET /v3/deployments

Query parameters

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

Permitted roles

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

Update a deployment

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

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


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

Definition

PATCH /v3/deployments/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Cancel a deployment

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

Definition

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

Permitted roles

Admin
Space Developer

Domains

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

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

The domain object

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

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

Create a domain

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

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

Definition

POST /v3/domains

Required parameters

Name Type Description
name string Name of the domain.

Optional parameters

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

Permitted roles

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

Get a domain

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

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

Definition

GET /v3/domains/:guid

Permitted roles

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

List domains

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

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

Retrieve all domains the user has access to.

Definition

GET /v3/domains

Query parameters

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

Permitted roles

All Roles

List domains for an organization

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

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

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

Definition

GET /v3/organizations/:guid/domains

Query parameters

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

Permitted roles

All Roles

Update a domain

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

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

Definition

PATCH /v3/domains/:guid

Optional parameters

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

Permitted roles

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

Delete a domain

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

Definition

DELETE /v3/domains/:guid

Permitted roles

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

Share a domain

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

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

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

Definition

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

Required parameters

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

Permitted roles

Role Notes
Admin
Org Manager

Unshare a domain

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

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

Definition

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

Permitted roles

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

Droplets

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

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

The droplet object

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

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

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

Buildpack droplet

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

Docker droplet

Name Type Description
image string Docker image name.

Create a droplet

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

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

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

Definition

POST /v3/droplets

Required parameters

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Get a droplet

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

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

Definition

GET /v3/droplets/:guid

Permitted roles

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

List droplets

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

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

Retrieve all droplets the user has access to.

Definition

GET /v3/droplets

Query parameters

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

Permitted roles

All Roles

List droplets for a package

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

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

Retrieve a list of droplets belonging to a package.

Definition

GET /v3/packages/:guid/droplets

Query parameters

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

Permitted roles

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

List droplets for an app

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

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

Retrieve a list of droplets belonging to an app.

Definition

GET /v3/apps/:guid/droplets

Query parameters

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

Permitted roles

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

Update a droplet

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

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

Definition

PATCH /v3/droplets/:guid

Optional parameters

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

Permitted roles

Admin
Org Manager
Space Developer
Space Manager

Delete a droplet

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

Definition

DELETE /v3/droplets/:guid

Permitted Roles

Admin
Space Developer

Copy a droplet

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

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

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

Definition

POST /v3/droplets?source_guid=:guid

Required query parameters

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

Required parameters

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

Permitted roles

Admin
Space Developer

Upload droplet bits

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

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

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

Definition

POST /v3/droplets/:guid/upload

Required parameters

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

Permitted roles

Admin
Space Developer

Environment Variable Groups

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

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

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

The environment variable group object

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

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

Get an environment variable group

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

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

Definition

GET /v3/environment_variable_groups/:name

Permitted roles

All Roles

Update environment variable group

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

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

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

Definition

PATCH /v3/environment_variable_groups/:name

Permitted roles

Admin

Feature Flags

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

The feature flag object

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

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

List of feature flags

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

Get a feature flag

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

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

Definition

GET /v3/feature_flags/:name

Permitted roles

All Roles

List feature flags

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

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

Retrieve all feature_flags.

Definition

GET /v3/feature_flags

Query parameters

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

Permitted roles

All Roles

Update a feature flag

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

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

Definition

PATCH /v3/feature_flags/:name

Optional parameters

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

Permitted roles

Admin

Info

Info endpoints expose Cloud Controller configuration information.

Get platform info

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

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

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

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

Definition

GET /v3/info

Authentication

No authentication required.

Isolation Segments

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

The isolation segment object

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

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

Create an isolation segment

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

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

Definition

POST /v3/isolation_segments

Required parameters

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

Permitted roles

Admin

Get an isolation segment

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

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

Definition

GET /v3/isolation_segments/:guid

Permitted roles

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

List isolation segments

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

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

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

Definition

GET /v3/isolation_segments

Query parameters

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

Permitted roles

All Roles

List organizations relationship

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

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

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

Definition

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

Permitted roles

All Roles

List spaces relationship

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

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

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

Definition

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

Permitted roles

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

Update an isolation segment

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

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

Definition

PATCH /v3/isolation_segments/:guid

Optional parameters

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

Permitted roles

Admin

Delete an isolation segment

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

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

Definition

DELETE /v3/isolation_segments/:guid

Permitted roles

Admin

Entitle organizations for an isolation segment

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

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

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

Definition

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

Required parameters

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

Permitted roles

Admin

Revoke entitlement to isolation segment for an organization

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

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

Definition

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

Permitted roles

Admin

Jobs

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

The job object

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

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

Get a job

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

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

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

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

Definition

GET /v3/jobs/:guid

Permitted roles

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

Organizations

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

The organization object

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

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

Create an organization

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

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

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

Definition

POST /v3/organizations

Required parameters

Name Type Description
name string Organization name

Optional parameters

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

Permitted roles

Admin

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

Get an organization

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

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

This endpoint retrieves the specified organization object.

Definition

GET /v3/organizations/:guid

Permitted roles

All Roles

List organizations

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

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

Retrieve all organizations the user has access to.

Definition

GET /v3/organizations

Query parameters

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

Permitted roles

All Roles

List organizations for isolation segment

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

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

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

Definition

GET /v3/isolation_segments/:guid/organizations

Query parameters

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

Permitted roles

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

Update an organization

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

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

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

Definition

PATCH /v3/organizations/:guid

Optional parameters

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

Permitted roles

Admin
Org Manager

Delete an organization

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

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

Definition

DELETE /v3/organizations/:guid

Permitted roles

Role Notes
Admin

Assign default isolation segment

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

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Org Manager

Get default isolation segment

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

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

Retrieve the default isolation segment for a given organization.

Definition

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

Permitted roles

All Roles

Get default domain

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

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

Retrieve the default domain for a given organization.

Definition

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

Permitted roles

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

Get usage summary

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

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

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

Definition

GET /v3/organizations/:guid/usage_summary

Permitted roles

All Roles

Organization Quotas

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

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

For more information, see the Cloud Foundry docs.

The organization quota object

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

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

Create an organization quota

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

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

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

To create an organization quota you must be an admin.

Definition

POST /v3/organization_quotas

Required parameters

Name Type Description
name string Name of the quota.

Optional parameters

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

Permitted roles

Role Notes
Admin

Get an organization quota

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

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

This endpoint gets an individual organization quota resource.

Definition

GET /v3/organization_quotas/:guid

Permitted roles

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

List organization quotas

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

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

This endpoint lists all organization quota resources.

Definition

GET /v3/organization_quotas

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

Permitted roles

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

Apply an organization quota to an organization

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

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

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

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

Definition

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

Required parameters

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

Permitted roles

Role Notes
Admin

Delete an organization quota

Organization quotas cannot be deleted when applied to any organizations.

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

Definition

DELETE /v3/organization_quotas/:guid

Permitted roles

Role Notes
Admin

Update an organization quota

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

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

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

Definition

PATCH /v3/organization_quotas/:guid

Optional parameters

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

Permitted roles

Role Notes
Admin

Packages

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

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

The package object

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

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

Bits package

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

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

Docker package

A Docker package references a Docker image from a registry.

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

Create a package

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

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

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

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

Definition

POST /v3/packages

Required parameters

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

Optional parameters

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

Conditional Parameters

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

Permitted roles

Admin
Space Developer

Get a package

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

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

Definition

GET /v3/packages/:guid

Permitted roles

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

List packages

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

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

Retrieve all packages the user has access to.

Definition

GET /v3/packages

Query parameters

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

Permitted roles

All Roles

List packages for an app

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

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

Definition

GET /v3/apps/:guid/packages

Query parameters

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

Permitted roles

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

Update a package

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

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

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

Definition

PATCH /v3/packages/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Delete a package

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

Definition

DELETE /v3/packages/:guid

Permitted Roles

Admin
Space Developer

Copy a package

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

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

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

Definition

POST /v3/packages?source_guid=:guid

Required query parameters

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

Required parameters

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

Permitted roles

Admin
Space Developer

Download package bits

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

You are being redirected.

This endpoint downloads the bits of an existing package.

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

Definition

GET /v3/packages/:guid/download

Permitted roles

Admin
Space Developer

Stage a package

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

Upload package bits

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

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

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

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

Definition

POST /v3/packages/:guid/upload

Optional parameters

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

Permitted roles

Admin
Space Developer

Processes

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

Web process type

The process object

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

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

The health check object

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

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

The process stats object

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

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

Get a process

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

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

Definition

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

Permitted roles

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

Get stats for a process

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

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

Definition

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

Permitted roles

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

List processes

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

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

Retrieve all processes the user has access to.

Definition

GET /v3/processes

Query parameters

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

Permitted roles

All Roles

List processes for app

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

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

Retrieves all processes belonging to an app.

Definition

GET /v3/apps/:guid/processes

Query parameters

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

Permitted roles

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

Update a process

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

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

Definition

PATCH /v3/processes/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Scale a process

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

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

Definition

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

Optional parameters

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

Permitted roles

Admin
Space Developer

Terminate a process instance

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

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

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

Definition

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

Permitted Roles

Admin
Space Developer

Resource Matches

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

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

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

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

The resource match object

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

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

Create a resource match

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

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

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

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

Definition

POST /v3/resource_matches

Required parameters

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

Permitted roles

All Roles

Roles

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

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

The role object

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

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

Valid role types

Create a role

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

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

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

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

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

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

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

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

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

Definition

POST /v3/roles

Required parameters

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

Permitted roles

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

Get a role

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

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

This endpoint gets an individual role resource.

Definition

GET /v3/roles/:guid

Query parameters

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

Permitted roles

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

List roles

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

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

This endpoint lists roles that the user has access to.

Definition

GET /v3/roles

Query parameters

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

Permitted roles

All Roles

Delete a role

This endpoint deletes an individual role.

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

Definition

DELETE /v3/roles/:guid

Permitted roles

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

Routes

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

The route object

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

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

The destination object

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

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

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

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

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

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

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

Create a route

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

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

Definition

POST /v3/routes

Required parameters

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

Optional parameters

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

Permitted roles

Role Notes
Admin
Space Developer

Get a route

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

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

Definition

GET /v3/routes/:guid

Query parameters

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

Permitted roles

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

List routes

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

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

Retrieve all routes the user has access to.

Definition

GET /v3/routes

Query parameters

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

Permitted roles

All Roles

List routes for an app

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

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

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

Definition

GET /v3/apps/:guid/routes

Query parameters

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

Permitted roles

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

Update a route

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

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

Definition

PATCH /v3/routes/:guid

Optional parameters

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

Permitted roles

Role Notes
Admin
Space Developer

Delete a route

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

Definition

DELETE /v3/routes/:guid

Permitted roles

Role Notes
Admin
Space Developer

Check reserved routes for a domain

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

  { "matching_route": true }

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

Definition

GET /v3/domains/:guid/route_reservations

Query parameters

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

Permitted roles

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

List destinations for a route

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

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

Retrieve all destinations associated with a route.

Definition

GET /v3/routes/:guid/destinations

Query parameters

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

Permitted roles

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

Insert destinations for a route

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

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

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

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

Definition

POST /v3/routes/:guid/destinations

Required parameters

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

Permitted roles

Role
Admin
Space Developer

Replace all destinations for a route

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

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

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

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

Definition

PATCH /v3/routes/:guid/destinations

Required parameters

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

Permitted roles

Role
Admin
Space Developer

Remove destination for a route

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

Remove a destination from a route.

Definition

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

Permitted roles

Role Notes
Admin
Space Developer

Delete unmapped routes for a space

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

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

Definition

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

Permitted roles

Role Notes
Admin
Space Developer

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

Service Instances

An instantiation of a service offering.

The service instance object

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

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

List service instances

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

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

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

This includes access granted by service instance sharing.

Definition

GET /v3/service_instances

Query parameters

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

Permitted roles

All Roles

List shared spaces relationship

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

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

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

Definition

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

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

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

Update a service instance

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

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

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

Definition

PATCH /v3/service_instances/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Share a service instance to other spaces

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

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Space Developer

Unshare a service instance from another space

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

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

Definition

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

Permitted roles

Admin
Space Developer

Spaces

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

The space object

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

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

Create a space

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

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

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

Definition

POST /v3/spaces

Required parameters

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

Optional parameters

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

Permitted roles

Admin
Org Manager

Get a space

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

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

This endpoint retrieves the specified space object.

Definition

GET /v3/spaces/:guid

Query parameters

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

Permitted roles

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

List spaces

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

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

Retrieve all spaces the user has access to.

Definition

GET /v3/spaces

Query parameters

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

Permitted roles

All Roles

Update a space

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

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

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

Definition

PATCH /v3/spaces/:guid

Optional parameters

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

Permitted roles

Admin
Org Manager
Space Manager

Delete a space

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

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

Definition

DELETE /v3/spaces/:guid

Permitted roles

Role Notes
Admin
Org Manager

Get assigned isolation segment

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

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

Definition

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

Permitted roles

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

Manage isolation segment

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

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

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

Definition

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

Required parameters

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

Permitted roles

Admin
Org Manager

Space Features

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

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

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

The space feature object

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

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

Get a space feature

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

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

Definition

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

Permitted roles

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

List space features

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

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

{
  "resources": [
    {
      "name": "ssh",
      "description": "Enable SSHing into apps in the space.",
      "enabled": false
    }
  ]
}

Definition

GET /v3/spaces/:guid/features

Permitted roles

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

Update space features

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

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

Definition

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

Permitted roles

Admin
Org Manager
Space Manager

Space Quotas

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

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

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

The space quota object

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

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

Create a space quota

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

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

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

Definition

POST /v3/space_quotas

Required parameters

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

Optional parameters

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

Permitted roles

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

Get a space quota

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

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

Definition

GET /v3/space_quotas/:guid

Permitted roles

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

Note: Response will not show any space guids that a user would not otherwise be able to see (see space view permissions).

List space quotas

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

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/space_quotas?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/space_quotas?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:41Z",
      "name": "don-quixote",
      "apps": {
        "total_memory_in_mb": 5120,
        "per_process_memory_in_mb": 1024,
        "total_instances": 10,
        "per_app_tasks": null
      },
      "services": {
        "paid_services_allowed": true,
        "total_service_instances": 10,
        "total_service_keys": 20
      },
      "routes": {
        "total_routes": 8,
        "total_reserved_ports": 20
      },
      "relationships": {
        "organizations": {
          "data": {
            "guid": "9b370018-c38e-44c9-86d6-155c76801104"
          }
        },
        "spaces": {
          "data": [
            {
              "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
            }
          ]
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
        },
        "organization": {
          "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
        }
      }
    },
    {
      "guid": "554bcf32-7032-4cb0-92bc-738f9d2089d3",
      "created_at": "2017-05-04T17:00:41Z",
      "updated_at": "2017-05-04T17:00:41Z",
      "name": "sancho-panza",
      "apps": {
        "total_memory_in_mb": 2048,
        "per_process_memory_in_mb": 1024,
        "total_instances": 5,
        "per_app_tasks": 2
      },
      "services": {
        "paid_services_allowed": true,
        "total_service_instances": 10,
        "total_service_keys": 20
      },
      "routes": {
        "total_routes": 8,
        "total_reserved_ports": 4
      },
      "relationships": {
        "organizations": {
          "data": {
            "guid": "9b370018-c38e-44c9-86d6-155c76801104"
          }
        },
        "spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/space_quotas/554bcf32-7032-4cb0-92bc-738f9d2089d3"
        },
        "organization": {
          "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
        }
      }
    }
  ]
}

This endpoint lists all space quota resources that the user has permission to view (see getting a space quota).

Definition

GET /v3/space_quotas

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

Permitted roles

Role
All Roles

Note: Space quotas in the response will not show any space guids that a user would not otherwise be able to see (see space view permissions).

Update a space quota

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

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

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

Definition

PATCH /v3/space_quotas/:guid

Optional parameters

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

Permitted roles

Role Notes
Admin
Org Manager Can update space quotas in the organization where they have this role.

Delete a space quota

Space quotas cannot be deleted when applied to any spaces.

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

Definition

DELETE /v3/space_quotas/:guid

Permitted roles

Role Notes
Admin
Org Manager Can delete space quotas within their managed organizations.

Apply a space quota to a space

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

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

This endpoint applies a space quota to one or more spaces.

Only an admin or an org manager in the quota’s parent organization can apply a space quota to a space.

Definition

POST /v3/space_quotas/:quota_guid/relationships/spaces

Required parameters

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

Permitted roles

Role Notes
Admin
Org Manager Can apply space quotas to spaces within their managed organizations.

Remove a space quota from a space

Example Request
curl "https://api.example.org/v3/space_quotas/:quota_guid/relationships/spaces/:space_guid" \
-X DELETE \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

This endpoint removes a space quota from a space.

Only an admin or an org manager in the quota’s parent organization can remove a space quota from a space.

Definition

DELETE /v3/space_quotas/:quota_guid/relationships/spaces/:space_guid

Permitted roles

Role Notes
Admin
Org Manager Can remove space quotas from spaces within their managed organizations.

Stacks

Stacks are the base operating system and file system that your application will execute in. A stack is how you configure applications to run against different operating systems (like Windows or Linux) and different versions of those operating systems (like Windows 2012 or Windows 2016).

An application’s lifecycle will specify which stack to execute the application in. Buildpacks can also be associated with a particular stack if they contain stack-specific logic. An application will automatically use buildpacks associated with the application’s configured stack.

Stacks are not used for apps with a Docker lifecycle.

The stack object

Example Stack object
{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

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

Create a stack

Example Request
curl "https://api.example.org/v3/stacks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my-stack",
    "description": "Here is my stack!",
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

POST /v3/stacks

Required parameters

Name Type Description
name string Name of the stack. Must be unique and no longer than 250 characters.

Optional parameters

Name Type Description Default
description string Description of the stack. Must no longer than 250 characters. null
metadata.labels (experimental) label object Labels applied to the stack.
metadata.annotations (experimental) annotation object Annotations applied to the stack.

Permitted roles

Admin

Get a stack

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

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

GET /v3/stacks/:guid

Permitted roles

All Roles

List stacks

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/stacks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/stacks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/stacks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
      "created_at": "2018-11-09T22:43:28Z",
      "updated_at": "2018-11-09T22:43:28Z",
      "name": "my-stack-1",
      "description": "This is my first stack!",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
        }
      }
    },
    {
      "guid": "81c916c9-c2f9-440e-8e73-102e79c4704h",
      "created_at": "2018-11-09T22:43:29Z",
      "updated_at": "2018-11-09T22:43:29Z",
      "name": "my-stack-2",
      "description": "This is my second stack!",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/stacks/81c916c9-c2f9-440e-8e73-102e79c4704h"
        }
      }
    }
  ]
}


Retrieve all stacks.

Definition

GET /v3/stacks

Query parameters

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

Permitted roles

All Roles

Update a stack

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

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

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { "key": "value" },
     "annotations": { "note": "detailed information" }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

PATCH /v3/stacks/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Delete a stack

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

Definition

DELETE /v3/stacks/:guid

Permitted roles

Admin

Tasks

Tasks are one-off jobs that are intended to perform a task, stop, and be cleaned up, freeing up resources.

Examples of this include database migrations, sending things, and batch jobs.

The task object

Example Task object
{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "relationships": {
    "app": {
      "data": {
        "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Name Type Description
sequence_id integer User-facing id of the task. This number is unique for every task associated with a given app.
name string Name of the task.
command string Command that will be executed. This field may be excluded based on a user’s role.
disk_in_mb integer Amount of disk to allocate for the task in MB.
memory_in_mb integer Amount of memory to allocate for the task in MB.
state string State of the task. Possible states are PENDING, RUNNING, SUCCEEDED, CANCELING, and FAILED
droplet_guid uuid The guid of the droplet that will be used to run the command.
result object Results from the task
result.failure_reason string Null if the task succeeds, contains the error message if it fails.
guid uuid Unique identifier for the task.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
relationships.app datetime The app the task belongs to.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the task.
metadata.annotations (experimental) annotation object Annotations applied to the task.

Create a task

Example Request with Command
curl "https://api.example.org/v3/apps/[guid]/tasks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "command": "rake db:migrate" }'
Example Request with Template Process
curl "https://api.example.org/v3/apps/[guid]/tasks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "template": { "process": {"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e"} } }'
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "relationships": {
    "app": {
      "data": {
        "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Definition

POST /v3/apps/:guid/tasks

Required parameters

Name Type Description
command[1] string Command that will be executed. NOTE: optional if a template.process.guid is provided

Optional parameters

Name Type Description Default
name string Name of the task. auto-generated
disk_in_mb[1] integer Amount of disk to allocate for the task in MB. operator-configured default_app_disk_in_mb
memory_in_mb[1] integer Amount of memory to allocate for the task in MB. operator-configured default_app_memory
droplet_guid uuid The guid of the droplet that will be used to run the command. the app’s current droplet
template.process.guid (experimental) uuid The guid of the process that will be used as a template. null
metadata.labels (experimental) label object Labels applied to the package.
metadata.annotations (experimental) annotation object Annotations applied to the package.

1 If not provided, and a template.process.guid is provided, this field will use the value from the process with the given guid.

Permitted roles

Admin
Space Developer

Get a task

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

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "relationships": {
    "app": {
      "data": {
        "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Retrieve a specific task. The command field may be excluded in the response based on the user’s role.

Definition

GET /v3/tasks/:guid

Permitted roles

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

List tasks

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/tasks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/tasks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/tasks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "sequence_id": 1,
      "name": "hello",
      "state": "SUCCEEDED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": null
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "relationships": {
        "app": {
          "data": {
            "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
    {
      "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
      "sequence_id": 2,
      "name": "migrate",
      "state": "FAILED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": "Exited with status 1"
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "relationships": {
        "app": {
          "data": {
            "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    }
  ]
}

Retrieve all tasks the user has access to. The command field is excluded in the response.

Definition

GET /v3/tasks

Query parameters

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

Permitted roles

All Roles

List tasks for an app

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "sequence_id": 1,
      "name": "hello",
      "state": "SUCCEEDED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": null
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "relationships": {
        "app": {
          "data": {
            "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
    {
      "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
      "sequence_id": 2,
      "name": "migrate",
      "state": "FAILED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": "Exited with status 1"
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "relationships": {
        "app": {
          "data": {
            "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    }
  ]
}

Retrieve tasks for an app the user has access to. The command field may be excluded in the response based on the user’s role.

Definition

GET /v3/apps/:guid/tasks

Query parameters

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

Permitted roles

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

Update a task

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

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

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "relationships": {
    "app": {
      "data": {
        "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Definition

PATCH /v3/tasks/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Cancel a task

Example Request
curl "https://api.example.org/v3/tasks/[guid]/actions/cancel" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "CANCELING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "relationships": {
    "app": {
      "data": {
        "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Cancels a running task.

Canceled tasks will initially be in state CANCELING and will move to state FAILED once the cancel request has been processed.

Cancel requests are idempotent and will be processed according to the state of the task when the request is executed.

Canceling a task that is in SUCCEEDED or FAILED state will return an error.

Definition

POST /v3/tasks/:guid/actions/cancel
PUT /v3/tasks/:guid/cancel (Deprecated)

Permitted roles

Admin
Space Developer

Users

Every Cloud Foundry action (pushing an application, creating a space) requires a user. Each Cloud Foundry installation has one pre-installed user, admin, which can create subsequent users. Users can be assigned roles which give them privileges to perform actions. For example, the Space Developer role grants a user permission to manage apps and services in a space (to push apps, scale apps, delete apps).

The user object

Example User object
  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "metadata": {
      "labels": {},
      "annotations":{}
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Name Type Description
guid uuid Unique identifier for the user.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
username string The name registered in UAA. Will be null for UAA clients and non-UAA users.
presentation_name string The name displayed for the user. For UAA users, this is the same as the username. For UAA clients, this is the UAA client ID.
origin string The identity provider for the UAA user. Will be null for UAA clients.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the user.
metadata.annotations (experimental) annotation object Annotations added to the user.

Create a user

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

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

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

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "metadata": {
      "labels": {},
      "annotations":{}
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

POST /v3/users

Required parameters

Name Type Description
guid string Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user’s GUID. In the case of UAA clients, this will match the UAA client ID.
metadata.labels (experimental) label object Labels applied to the user.
metadata.annotations (experimental) annotation object Annotations added to the user.

Permitted roles

Role Notes
Admin

Get a user

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

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "metadata": {
      "labels": {},
      "annotations":{}
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

GET /v3/users/:guid

Permitted roles

Roles Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor Can only view users affiliated with their org
Org Billing Manager Can only view users affiliated with their org
Org Manager Can only view users affiliated with their org
Space Auditor Can only view users affiliated with their org
Space Developer Can only view users affiliated with their org
Space Manager Can only view users affiliated with their org

Note: A user can always see themselves with this endpoint, regardless of role.

List users

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/users?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/users?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/users?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
     {
      "guid": "client_id",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "username": null,
      "presentation_name": "client_id",
      "origin": null,
      "metadata": {
        "labels": {},
        "annotations":{}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
        }
      }
    },
    {
      "guid": "9da93b89-3f89-4f05-7238-8a2b123c79l9",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "username": "some-name",
      "presentation_name": "some-name",
      "origin": "uaa",
      "metadata": {
        "labels": {},
        "annotations":{}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9"
        }
      }
    }
  ]
}


Retrieve all users that the current user can see.

Definition

GET /v3/users

Query parameters

Name Type Description
guids list of strings Comma-delimited list of user guids to filter by.
usernames list of strings Comma-delimited list of usernames to filter by.
origins list of strings Comma-delimited list of user origins (user stores) to filter by. For example, users authenticated by UAA have the origin “uaa”; users authenticated by an LDAP provider have the origin “ldap”. When filtering by origins, usernames must be included.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

Roles Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor Can only view users affiliated with their org
Org Billing Manager Can only view users affiliated with their org
Org Manager Can only view users affiliated with their org
Space Auditor Can only view users affiliated with their org
Space Developer Can only view users affiliated with their org
Space Manager Can only view users affiliated with their org

Update a user

Update a user’s metadata.

Example Request
curl "https://api.example.org/v3/users/24d59a1e-2613-4255-86a2-e0454cc6e261" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
  "metadata": {
    "labels": { "enviroment": "production" },
    "annotations": { "note": "detailed information" }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "metadata": {
      "labels": { "enviroment": "production" },
      "annotations": { "note": "detailed information" }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

PATCH /v3/users

Required parameters

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

Permitted roles

Admin

Delete a user

All roles associated with a user will be deleted if the user is deleted.

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

Definition

DELETE /v3/users/:guid

Permitted roles

Role Notes
Admin

Experimental Resources

App Manifest

The app manifest is a method for applying bulk configuration to an app and its underlying processes.

The app manifest specification

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

App-level configuration

This configuration is specified at the top-level and applies to all of the app’s processes.

Field Description
buildpacks Must be an Array.
a) An empty array, which will automatically select the appropriate default buildpack according to the coding language.
b) An array of one or more URLs pointing to buildpacks.
c) An array of one or more installed buildpack names.
Replaces the legacy buildpack field.
env A key-value hash of environment variables to be used for the app when running.
no-route Boolean value. When set to true, any routes specified with the routes attribute will be ignored and any existing routes will be removed; ignored if false.
processes List of configurations for individual process types. See Process-level configuration.
random-route Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified.
default-route Boolean value. If true, a route for the app will be created using the app name as the hostname and the containing organization’s default domain as the domain. If false, if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored and results in noop.
routes An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path
services An array of service-instances to bind to the app. See Service-level configuration.
sidecars An array of configurations for individual sidecars. See Sidecar-level configuration.
stack The root filesystem to use with the buildpack, for example cflinuxfs3.
metadata.labels (experimental) Labels applied to the app.
metadata.annotations (experimental) Annotations applied to the app.
buildpack DEPRECATED in favor of the buildpacks field above.
a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language.
b) A URL pointing to a buildpack.
c) Name of an installed buildpack.

Process-level configuration

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

With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.

If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.

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

Service-level configuration

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

Field Description
name (Required) Service instance name. The name of the service instance to be bound to.
parameters A map of arbitrary key/value pairs to send to the service broker during binding.

Sidecar-level configuration

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

Field Description
name (Required) Sidecar name. The identifier for the sidecars to be configured.
command The command used to start the sidecar.
process_types List of processes to associate sidecar with.
memory Memory in mb that the sidecar will be allocated.

Generate an app manifest

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

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

Generate a manifest for an app and its underlying processes.

Definition

GET /v3/apps/:guid/manifest

Permitted Roles

Admin
Admin Read-Only
Space Developer

Apply an app manifest

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

Apply changes specified in a manifest to an app and its underlying processes. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.

Definition

POST /v3/apps/:guid/actions/apply_manifest

Permitted Roles

Admin
Space Developer

App Restart

Restart an app

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

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

Definition

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

Permitted roles

Admin
Space Developer

Revisions

Revisions represent code used by an application at a specific time. The most recent revision for a running application represents code and configuration currently running in Cloud Foundry.

Revision are created when the following is changed:

Each time a new revision is created the reason(s) for the revisions creation will be appended to its description field.

By default the cloud foundry API retains at most 100 revisions per app.

The revision object

Example Revision object
{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "processes": {
    "web": {
      "command": "bundle exec rackup"
    }
  },
  "sidecars": [
    {
      "name": "auth-sidecar",
      "command": "bundle exec sidecar",
      "process_types": ["web"],
      "memory_in_mb": 300
    }
  ],
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
    }
  }
}

Name Type Description
guid uuid Unique identifier for the revision.
version integer Human-readable identifier for the revision. Starts at 1, increments by 1 for each new revision of the app, and rolls back over to 1 at 9999.
droplet object The droplet used by a process running the revision.
processes process snapshot object An object representing process types at this revision.
sidecars array of sidecar snapshot objects ] The array of sidecars used by processes running the revision.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
description string A short description of the reason for revision.
relationships.app to-one relationship The app the revision is associated with.
metadata.labels (experimental) label object Labels applied to the revision.
metadata.annotations (experimental) annotation object Annotations applied to the revision.
links links object Links to related resources.

The process snapshot object

Example Process Snapshot object
{
  "web": {
    "command": "bundle exec rackup"
  },
  "worker": {
    "command": "bundle exec work"
  }
}

The process snapshot object is a map of process types to objects. Each object contains the command that the given process type was running at this revision.

The sidecar snapshot object

Example Sidecar Snapshot object
{
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300
}
Name Type Description
name string Human-readable name for the sidecar.
command string The command used to start the sidecar.
process_types array of strings A list of process types the sidecar applies to.
memory_in_mb integer Reserved memory for sidecar.

Get a revision

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

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "processes": {
    "web": {
      "command": "bundle exec rackup"
    }
  },
  "sidecars": [
    {
      "name": "auth-sidecar",
      "command": "bundle exec sidecar",
      "process_types": ["web"],
      "memory_in_mb": 300
    }
  ],
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
    }
  }
}

Definition

GET /v3/revisions/:guid

Permitted roles

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

List revisions for an app

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

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "version": 1,
      "droplet": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      },
      "processes": {
        "web": {
          "command": "bundle exec rackup"
        }
      },
      "sidecars": [
        {
          "name": "auth-sidecar",
          "command": "bundle exec sidecar",
          "process_types": ["web"],
          "memory_in_mb": 300
        }
      ],
      "description": "Initial revision.",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
        },
        "environment_variables": {
          "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
        }
      }
    }
  ]
}

Retrieve revisions for an app the user has access to.

Definition

GET /v3/apps/:guid/revisions

Query parameters

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

Permitted roles

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

List deployed revisions for an app

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

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "version": 1,
      "droplet": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      },
      "processes": {
        "web": {
          "command": "bundle exec rackup"
        }
      },
      "sidecars": [
        {
          "name": "auth-sidecar",
          "command": "bundle exec sidecar",
          "process_types": ["web"],
          "memory_in_mb": 300
        }
      ],
      "description": "Initial revision.",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
        },
        "environment_variables": {
          "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
        }
      }
    }
  ]
}

Retrieve deployed revisions for an app the user has access to. Deployed revisions are revisions that are linked to started processes in the app.

Definition

GET /v3/apps/:guid/revisions/deployed

Query parameters

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

Permitted roles

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

Update a revision

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

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

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "processes": {
    "web": {
      "command": "bundle exec rackup"
    }
  },
  "sidecars": [
    {
      "name": "auth-sidecar",
      "command": "bundle exec sidecar",
      "process_types": ["web"],
      "memory_in_mb": 300
    }
  ],
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "environment_variables": {
      "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
    }
  }
}

Definition

PATCH /v3/revisions/:guid

Optional parameters

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

Permitted roles

Admin
Space Developer

Security Groups

Security groups are collections of egress traffic rules that can be applied to the staging or running state of applications.

Security groups can either be applied globally or at the space-level.

Security groups can only allow (whitelist) traffic. They cannot be used to disallow (blacklist) traffic.

The security group object

Example Security Group object
{
  "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
  "created_at": "2020-02-20T17:42:08Z",
  "updated_at": "2020-02-20T17:42:08Z",
  "name": "my-group0",
  "globally_enabled": {
    "running": true,
    "staging": false
  },
  "rules": [
    {
      "protocol": "tcp",
      "destination": "10.10.10.0/24",
      "ports": "443,80,8080"
    },
    {
      "protocol": "icmp",
      "destination": "10.10.10.0/24",
      "type": 8,
      "code": 0,
      "description": "Allow ping requests to private services"
    }
  ],
  "relationships": {
    "staging_spaces": {
      "data": [
        { "guid": "space-guid-1" },
        { "guid": "space-guid-2" }
      ]
    },
    "running_spaces": {
      "data": []
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
    }
  }
}

Name Type Description
name string Name of the security group.
globally_enabled object Object that controls if the group is applied globally to the lifecycle of all applications.
globally_enabled.running boolean Specifies whether the group should be applied globally to all running applications.
globally_enabled.staging boolean Specifies whether the group should be applied globally to all staging applications.
rules array of rule objects Rules that will be applied by this security group.
relationships.staging_spaces to-many relationship A relationship to the spaces where the security_group is applied to applications during staging.
relationships.running_spaces to-many relationship A relationship to the spaces where the security_group is applied to applications during runtime.

The rule object

Name Type Description Required Default
protocol string Protocol type. Valid values are tcp, udp, icmp, or all yes N/A
destination string Destinations that the rule applies to. Valid CIDR, IP address, or IP address range yes N/A
ports string Ports that the rule applies to. Can be a single port (9000), a comma-separated list (9000,9001), or a range (9000-9200). no null
type integer Type required for ICMP protocol. Valid values are between -1 and 255 (inclusive) no null
code integer Code required for ICMP protocol. Valid values are between -1 and 255 (inclusive) no null
description string A description for the rule no null
log boolean Enable logging for rule no null

Create a security group

Example Request
curl "https://api.example.org/v3/security_groups" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
  "name": "my-group0",
  "rules": [
    {
      "protocol": "tcp",
      "destination": "10.10.10.0/24",
      "ports": "443,80,8080"
    },
    {
      "protocol": "icmp",
      "destination": "10.10.10.0/24",
      "type": 8,
      "code": 0,
      "description": "Allow ping requests to private services"
    }
  ]
}'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
  "created_at": "2020-02-20T17:42:08Z",
  "updated_at": "2020-02-20T17:42:08Z",
  "name": "my-group0",
  "globally_enabled": {
    "running": true,
    "staging": false
  },
  "rules": [
    {
      "protocol": "tcp",
      "destination": "10.10.10.0/24",
      "ports": "443,80,8080"
    },
    {
      "protocol": "icmp",
      "destination": "10.10.10.0/24",
      "type": 8,
      "code": 0,
      "description": "Allow ping requests to private services"
    }
  ],
  "relationships": {
    "staging_spaces": {
      "data": [
        { "guid": "space-guid-1" },
        { "guid": "space-guid-2" }
      ]
    },
    "running_spaces": {
      "data": []
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
    }
  }
}

Definition

POST /v3/security_groups

Required parameters

Name Type Description
name string Name of the security group.

Optional parameters

Name Type Description
globally_enabled object Object that controls if the group is applied globally to the lifecycle of all applications.
globally_enabled.running boolean Specifies whether the group should be applied globally to all running applications.
globally_enabled.staging boolean Specifies whether the group should be applied globally to all staging applications.
rules array of rule objects Rules that will be applied by this security group.
relationships.staging_spaces to-many relationship A relationship to the spaces where the security group is applied to applications during staging.
relationships.running_spaces to-many relationship A relationship to the spaces where the security group is applied to applications during runtime.

Permitted roles

Admin

Get a security group

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

{
  "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
  "created_at": "2020-02-20T17:42:08Z",
  "updated_at": "2020-02-20T17:42:08Z",
  "name": "my-group0",
  "globally_enabled": {
    "running": true,
    "staging": false
  },
  "rules": [
    {
      "protocol": "tcp",
      "destination": "10.10.10.0/24",
      "ports": "443,80,8080"
    },
    {
      "protocol": "icmp",
      "destination": "10.10.10.0/24",
      "type": 8,
      "code": 0,
      "description": "Allow ping requests to private services"
    }
  ],
  "relationships": {
    "staging_spaces": {
      "data": [
        { "guid": "space-guid-1" },
        { "guid": "space-guid-2" }
      ]
    },
    "running_spaces": {
      "data": []
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
    }
  }
}

Definition

GET /v3/security_groups/:guid

Permitted roles

Role Notes
Admin Can see all security groups
Admin Read-Only Can see all security groups
Global Auditor Can see all security groups
Org Auditor Can see globally enabled security groups
Org Billing Manager Can see globally enabled security groups
Org Manager Can see globally enabled security groups or groups associated with a space they can see
Space Auditor Can see globally enabled security groups or groups associated with a space they can see
Space Developer Can see globally enabled security groups or groups associated with a space they can see
Space Manager Can see globally enabled security groups or groups associated with a space they can see

List security groups

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

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/security_groups?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/security_groups?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
      "created_at": "2020-02-20T17:42:08Z",
      "updated_at": "2020-02-20T17:42:08Z",
      "name": "my-group0",
      "globally_enabled": {
        "running": true,
        "staging": false
      },
      "rules": [
        {
          "protocol": "tcp",
          "destination": "10.10.10.0/24",
          "ports": "443,80,8080"
        },
        {
          "protocol": "icmp",
          "destination": "10.10.10.0/24",
          "type": 8,
          "code": 0,
          "description": "Allow ping requests to private services"
        }
      ],
      "relationships": {
        "staging_spaces": {
          "data": [
            { "guid": "space-guid-1" },
            { "guid": "space-guid-2" }
          ]
        },
        "running_spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
        }
      }
    },
    {
      "guid": "a89a788e-671f-4549-814d-e34c1b2f533a",
      "created_at": "2020-02-20T17:42:08Z",
      "updated_at": "2020-02-20T17:42:08Z",
      "name": "my-group1",
      "globally_enabled": {
        "running": true,
        "staging": true
      },
      "rules": [],
      "relationships": {
        "staging_spaces": {
          "data": []
        },
        "running_spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a"
        }
      }
    }
  ]
}

Definition

GET /v3/security_groups

Query parameters

Name Type Description
guids list of strings Comma-delimited list of security group guids to filter by.
names list of strings Comma-delimited list of security group names to filter by.
globally_enabled_running boolean If true, only include the security groups that are enabled for running.
globally_enabled_staging boolean If true, only include the security groups that are enabled for staging.
running_space_guids list of strings Comma-delimited list of space guids to filter by.
staging_space_guids list of strings Comma-delimited list of space guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.

Permitted roles

Role Notes
Admin Can see all security groups
Admin Read-Only Can see all security groups
Global Auditor Can see all security groups
Org Auditor Can see globally–enabled security groups
Org Billing Manager Can see globally–enabled security groups
Org Manager Can see globally–enabled security groups or groups associated with a space they can see
Space Auditor Can see globally–enabled security groups or groups associated with a space they can see
Space Developer Can see globally–enabled security groups or groups associated with a space they can see
Space Manager Can see globally–enabled security groups or groups associated with a space they can see

List running security groups for a space

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

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/running_security_groups?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/running_security_groups?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
      "created_at": "2020-02-20T17:42:08Z",
      "updated_at": "2020-02-20T17:42:08Z",
      "name": "my-group0",
      "globally_enabled": {
        "running": true,
        "staging": false
      },
      "rules": [
        {
          "protocol": "tcp",
          "destination": "10.10.10.0/24",
          "ports": "443,80,8080"
        },
        {
          "protocol": "icmp",
          "destination": "10.10.10.0/24",
          "type": 8,
          "code": 0,
          "description": "Allow ping requests to private services"
        }
      ],
      "relationships": {
        "staging_spaces": {
          "data": [
            { "guid": "space-guid-1" },
            { "guid": "space-guid-2" }
          ]
        },
        "running_spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
        }
      }
    },
    {
      "guid": "a89a788e-671f-4549-814d-e34c1b2f533a",
      "created_at": "2020-02-20T17:42:08Z",
      "updated_at": "2020-02-20T17:42:08Z",
      "name": "my-group1",
      "globally_enabled": {
        "running": true,
        "staging": true
      },
      "rules": [],
      "relationships": {
        "staging_spaces": {
          "data": []
        },
        "running_spaces": {
          "data": []
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a"
        }
      }
    }
  ]
}

Definition

GET /v3/spaces/:guid/running_security_groups

Query parameters

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

Permitted roles

Role Notes
Admin Can see all security groups
Admin Read-Only Can see all security groups
Global Auditor Can see all security groups
Org Manager Can see globally-enabled security groups and groups associated with spaces in their managed organizations
Space Auditor Can see globally-enabled security groups and groups associated with spaces where they have this role
Space Developer Can see globally-enabled security groups and groups associated with spaces where they have this role
Space Manager Can see globally-enabled security groups and groups associated with spaces where they have this role

Service Bindings

Service bindings are relations between a service instance and an app; to use a service instance with an app, you must first bind them together.

Not all services support binding, as some services deliver value to users directly without integration with an application.

The service binding object

Example Service Binding object
{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Name Type Description
type string Service binding type. Valid value is app.
data object Data returned from the service broker for the service instance. Valid values are credentials, syslog_drain_url and (experimental) volume_mounts.
guid uuid Unique identifier for the service binding.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.

Create a service binding

Example Request
curl "https://api.example.org/v3/service_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "app",
    "relationships": {
      "app": {
        "data": {
          "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      },
      "service_instance": {
        "data": {
          "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
        }
      }
    },
    "data": {
      "parameters": {
        "some_object_id": "for_the_service_broker"
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Definition

POST /v3/service_bindings

Required parameters

Name Type Description
type string Service binding type. Valid value is app.
relationships.app to-one relationship A relationship to an app.
relationships.service_instance to-one relationship A relationship to a service_instance.

Optional parameters

Name Type Description Default
data.parameters object Additional configuration parameters for the service binding. {}

Permitted roles

Admin
Space Developer

Get a service binding

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

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

Definition

GET /v3/service_bindings/:guid

Permitted roles

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

List service bindings

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_bindings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "type": "app",
      "data": {
        "credentials": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "syslog_drain_url": "syslog://drain.url.example.org",
        "volume_mounts": []
      },
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        },
        "service_instance": {
          "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      }
    },
    {
      "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
      "type": "app",
      "data": {
        "credentials": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "syslog_drain_url": "syslog://drain.url.example.org",
        "volume_mounts": []
      },
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "service_instance": {
          "href": "https://api.example.org/v3/service_instances/8bf356j3-9e18-45b1-3333-124163f31f9e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      }
    }
  ]
}

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

Definition

GET /v3/service_bindings

Query parameters

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

Permitted roles

All Roles

Delete a service binding

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

Definition

DELETE /v3/service_bindings/:guid

Permitted Roles

Admin
Space Developer

Service Brokers

Service brokers manage the lifecycle of services. On behalf of users, Cloud Controller will interact with service brokers to provision, get access to and manage access to the service offerings and plans they offer.

Admins can create and manage service brokers that are globally available, i.e., the service broker and its associated resources (service offerings and plans) can be made available to all users.

Space Developers can create and manage space-scoped service brokers. A space-scoped broker and its associated resources will only be available in the space the service broker was created.

The service broker object

Example Service Broker object
{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "name": "my_service_broker",
  "url": "https://example.service-broker.com",
  "available": true,
  "status": "available",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "metadata": {
    "labels": {
      "type": "dev"
    },
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_offerings": {
      "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

Name Type Description
guid uuid Unique identifier for the service broker.
name string Name of the service broker.
url string URL of the service broker.
available boolean Whether or not the service broker is available.
status string Availability status of the service broker.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
relationships.space to-one relationship The space the service broker is restricted to. Omitted for globally available service brokers.
metadata.labels (experimental) label object Labels applied to the service broker.
metadata.annotations (experimental) annotation object Annotations added to the service broker.
links links object Links to related resources.

Create a service broker

Example Request
curl "https://api.example.org/v3/service_brokers" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_service_broker",
    "url": "https://example.service-broker.com",
    "authentication": {
      "type": "basic",
      "credentials": {
        "username": "us3rn4me",
        "password": "p4ssw0rd"
      }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  }'
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint creates a new service broker and a job to synchronize the service offerings and service plans with those in the broker’s catalog. The Location header refers to the created job which syncs the broker with the catalog.

Definition

POST /v3/service_brokers

Required parameters

Name Type Description
name string Name of the service broker.
url string URL of the service broker.
authentication authentication Credentials used to authenticate against the service broker.

Optional parameters

Name Type Description
relationships.space to-one relationship If set, restricts the service broker to the specified space.
metadata.labels (experimental) label object Labels applied to the service broker.
metadata.annotations (experimental) annotation object Annotations applied to the service broker.

The authentication object

Name Type Description
type string Type of the authentication mechanisms that can be used. Valid value is basic.
credentials object Credentials for given authentication type.
Example basic authentication
{
  "type": "basic",
  "credentials": {
    "username": "admin",
    "password": "secretpassw0rd"
  }
}
Basic authentication credentials
Name Type Description
username string The username with which to authenticate against the service broker.
password string The password with which to authenticate against the service broker.

Permitted roles

Admin
Space Developer*

*Space Developers can only create space-scoped brokers. Space-scoped brokers can only be created when the space_scoped_private_broker_creation feature flag is true.

Get a service broker

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

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "name": "my_service_broker",
  "url": "https://example.service-broker.com",
  "available": true,
  "status": "available",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "metadata": {
    "labels": {
      "type": "dev"
    },
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_offerings": {
      "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

This endpoint retrieves the service broker by GUID.

Definition

GET /v3/service_brokers/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Space Developer (only space-scoped brokers)

List service brokers

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_brokers?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "name": "my_service_broker",
      "url": "https://example.service-broker.com",
      "available": true,
      "status": "available",
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "relationships": {} ,
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        },
        "service_offerings": {
          "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        }
      }
    },
    {
      "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
      "name": "another_service_broker",
      "url": "https://another-example.service-broker.com",
      "available": true,
      "status": "available",
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "relationships": {
        "space": {
          "data": {
            "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_brokers/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "service_offerings": {
          "href": "https://api.example.org/v3/service_offerings?service_broker_guids=7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  ]
}

This endpoint retrieves the service brokers the user has access to.

Definition

GET /v3/service_brokers

Query parameters

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

Permitted roles

Admin
Admin Read-Only
Global Auditor
Space Developer (only space-scoped brokers)

Update a service broker

Example Request
curl "https://api.example.org/v3/service_brokers/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_service_broker",
    "url": "https://example.service-broker.com",
    "authentication": {
      "type": "basic",
      "credentials": {
        "username": "us3rn4me",
        "password": "p4ssw0rd"
      }
    },
    "metadata": {
      "labels": {"key": "value"},
      "annotations": {"note": "detailed information"}
    }
  }'
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint updates a broker and creates a job to synchronize the service offerings and service plans with those in the broker’s catalog. The Location header refers to the created job which syncs the broker with the catalog. Service Brokers that are in the process of being synchronized or deleted cannot be updated.

Definition

PATCH /v3/service_brokers/[guid]

Optional parameters

Name Type Description
name string Name of the service broker.
url string URL of the service broker.
authentication authentication Credentials used to authenticate against the service broker.
metadata.labels (experimental) label object Labels applied to the service broker.
metadata.annotations (experimental) annotation object Annotations applied to the service broker.

The authentication object

Name Type Description
type string Type of the authentication mechanisms that can be used. Valid value is basic.
credentials object Credentials for given authentication type.
Example basic authentication
{
  "type": "basic",
  "credentials": {
    "username": "admin",
    "password": "secretpassw0rd"
  }
}
Basic authentication credentials
Name Type Description
username string The username with which to authenticate against the service broker.
password string The password with which to authenticate against the service broker.

Permitted roles

Admin
Space Developer (only space-scoped brokers)

Delete a service broker

Example Request
curl "https://api.example.org/v3/service_brokers/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788

This endpoint creates a job to delete an existing service broker. The Location header refers to the created job.

Definition

DELETE /v3/service_brokers/:guid

Permitted roles

Admin
Space Developer (only space-scoped brokers)

Service Offerings

Service Offerings represent the services offered by Service Brokers. A Service Broker will have one or more Service Offerings. A Service Offering will have one or more Service Plans. Service Offerings and Service Plans are created and updated when a Service Broker is registered or updated.

Visibility of Service Offerings

This table shows the Service Offerings that different roles can see. The Service Offerings that a user can see relate to their Space and Organization roles, regardless of which Space or Organization is being targeted.

A Service Offering can be seen when at least one of its Service Plans can be seen. Service Plans may be configured to be Public, or they may be configured with a relationship to a restricted list of Organizations.

Service Offerings and Service Plans from a space-scoped Service Broker cannot have their visibility configured. They are only visible to members of that Space.

Role Public Plans Restricted Plans From space-scoped Service Brokers
Admin All All All
Admin Read All All All
Global Auditor All All All
Org Manager All In Organisation None
Org Auditor All In Organisation None
Org Billing All In Organisation None
Space Manager All In Organisation In Space
Space Developer All In Organisation In Space
Space Auditor All In Organisation In Space
Unauthenticated All* None None

*Unless the hide_marketplace_from_unauthenticated_users feature flag is true

The Service Offering object

Example Service Offering object
{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_service_offering",
  "description": "Provides my service",
  "available": true,
  "tags": ["relational", "caching"],
  "requires": [],
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "shareable": true,
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "shareable": true
    },
    "features": {
      "plan_updateable": true,
      "bindable": true,
      "instances_retrievable": true,
      "bindings_retrievable": true,
      "allow_context_updates": false
    }
  },
  "relationships": {
    "service_broker": {
      "data": {
        "name": "my_service_broker",
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_plans": {
      "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_broker": {
      "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    }
  }
}


Name Type Description
guid uuid Unique identifier for the Service Offering.
name string Name of the Service Offering.
description string Description of the Service Offering.
available boolean Whether or not the Service Offering is available.
tags list of strings Descriptive tags for the Service Offering.
requires list_of_strings A list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are syslog_drain, route_forwarding and volume_mount.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
shareable boolean Whether or not Service Instances of this Service Offering can be shared across Organizations and Spaces.
broker_catalog object This object contains information obtained from the Service Broker Catalog.
broker_catalog.id string The identifier that the Service Broker provided for this Service Offering.
broker_catalog.metadata object Additional information provided by the Service Broker.
broker_catalog.features.plan_updateable boolean Whether the Service Offering supports upgrade/downgrade for Service Plans by default
broker_catalog.features.bindable boolean Specifies whether Service Instances of the service can be bound to applications.
broker_catalog.features.instances_retrievable boolean Specifies whether the Fetching a Service Instance endpoint is supported for all Service Plans.
broker_catalog.features.bindings_retrievable boolean Specifies whether the Fetching a Service Binding endpoint is supported for all Service Plans.
broker_catalog.features.allow_context_updates boolean Specifies whether Service Instance updates relating only to context are propagated to the Service Broker.
relationships.service_broker to-one relationship The Service Broker that provides this Service Offering.
metadata.labels (experimental) label object Labels applied to the Service Offering.
metadata.annotations (experimental) annotation object Annotations added to the Service Offering.
links links object Links to related resources.

Get a Service Offering

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

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_service_offering",
  "description": "Provides my service",
  "available": true,
  "tags": ["relational", "caching"],
  "requires": [],
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "shareable": true,
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "shareable": true
    },
    "features": {
      "plan_updateable": true,
      "bindable": true,
      "instances_retrievable": true,
      "bindings_retrievable": true,
      "allow_context_updates": false
    }
  },
  "relationships": {
    "service_broker": {
      "data": {
        "name": "my_service_broker",
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_plans": {
      "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_broker": {
      "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    }
  }
}


This endpoint retrieves the service offering by GUID.

Definition

GET /v3/service_offerings/:guid

Permitted roles

All Roles
Unauthenticated Users

List service offerings

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_offerings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_offerings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_offerings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
      "name": "my_service_offering",
      "description": "Provides my service",
      "available": true,
      "tags": ["relational", "caching"],
      "requires": [],
      "created_at": "2019-11-28T13:44:02Z",
      "updated_at": "2019-11-28T13:44:02Z",
      "shareable": true,
      "broker_catalog": {
        "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
        "metadata": {
          "shareable": true
        },
        "features": {
          "plan_updateable": true,
          "bindable": true,
          "instances_retrievable": true,
          "bindings_retrievable": true,
          "allow_context_updates": false
        }
      },
      "relationships": {
        "service_broker": {
          "data": {
            "name": "my_service_broker",
            "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
        },
        "service_plans": {
          "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
        },
        "service_broker": {
          "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
        }
      }
    },
    {
      "guid": "20e6cd62-12bb-11ea-90d1-7bfec2c75bcd",
      "name": "other_service_offering",
      "description": "Provides another service",
      "available": true,
      "tags": ["caching"],
      "requires": [],
      "created_at": "2019-11-29T16:44:02Z",
      "updated_at": "2019-11-29T16:44:02Z",
      "shareable": true,
      "broker_catalog": {
        "id": "3cb11822-12bb-11ea-beb1-a350dc7453b9",
        "metadata": {
          "shareable": true
        },
        "features": {
          "plan_updateable": true,
          "bindable": true,
          "instances_retrievable": true,
          "bindings_retrievable": true,
          "allow_context_updates": false
        }
      },
      "relationships": {
        "service_broker": {
          "data": {
            "name": "my_service_broker",
            "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_offerings/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
        },
        "service_plans": {
          "href": "https://api.example.org/v3/service_plans?service_offering_guids=20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
        },
        "service_broker": {
          "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
        }
      }
    }
  ]
}

This endpoint retrieves the service offerings the user has access to.

Definition

GET /v3/service_offerings

Query parameters

Name Type Description
names list of strings Comma-delimited list of names to filter by.
available boolean Filter by the available property. Valid values are true or false.
service_broker_guids list of strings Comma-delimited list of Service Broker GUIDs to filter by.
service_broker_names list of strings Comma-delimited list of Service Broker names to filter by.
space_guids list of strings Comma-delimited list of Space GUIDs to filter by.
organization_guids list of strings Comma-delimited list of Organization GUIDs to filter by.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles
Unauthenticated Users

Update a service offering

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

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_service_offering",
  "description": "Provides my service",
  "available": true,
  "tags": ["relational", "caching"],
  "requires": [],
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "shareable": true,
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "shareable": true
    },
    "features": {
      "plan_updateable": true,
      "bindable": true,
      "instances_retrievable": true,
      "bindings_retrievable": true,
      "allow_context_updates": false
    }
  },
  "relationships": {
    "service_broker": {
      "data": {
        "name": "my_service_broker",
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_plans": {
      "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
    },
    "service_broker": {
      "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    }
  }
}


This endpoint updates a Service Offering with labels and annotations.

Definition

PATCH /v3/service_offerings/[guid]

Optional parameters

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

Permitted roles

Admin
Space Developer (only for service offerings from space-scoped brokers)

Delete a service offering

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

This endpoint deletes a Service Offering. This is typically used to remove orphan Service Offerings from the Cloud Foundry database when they have been removed from the Service Broker catalog, or when the Service Broker has been removed.

Note that this operation only affects the Cloud Foundry database, and no attempt is made to contact the Service Broker.

Definition

DELETE /v3/service_offerings/:guid

Query parameters

Name Type Description
purge boolean If true, any service plans, instances, and bindings associated with this service offering will also be deleted.

Permitted roles

Admin
Space Developer (only service offerings from space-scoped brokers)

Service Plans

Service Plans represent the service plans offered by a Service Offering. A Service Offering will have one or more Service Plans. Service Offerings and Service Plans are created and updated when a Service Broker is registered or updated.

The Service Plan object

Example Service Plan object
{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_big_service_plan",
  "description": "Big",
  "visibility_type": "public",
  "available": true,
  "free": false,
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "maintenance_info": {
    "version": "1.0.0+dev4",
    "description": "Database version 7.8.0"
  },
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "custom-key": "custom-information"
    },
    "maximum_polling_duration": null,
    "features": {
      "plan_updateable": true,
      "bindable": true
    }
  },
  "schemas": {
    "service_instance": {
      "create": {
        "parameters": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "billing-account": {
              "description": "Billing account number used to charge use of shared fake server.",
              "type": "string"
            }
          }
        }
      },
      "update": {}
    },
    "service_binding": {
      "create": {}
    }
  },
  "relationships": {
    "service_offering": {
      "data": {
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
    },
    "service_offering": {
      "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    },
    "visibility": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
    }
  }
}


Name Type Description
guid uuid Unique identifier for the Service Plan.
name string Name of the Service Plan.
description string Description of the Service Plan.
available boolean Whether or not the Service Plan is available.
visibility_type string Denotes the visibility of the plan. Can be public, admin, organization, space. See list of visibility types.
free boolean Whether or not the Service Plan is free of charge.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
maintenance_info object Maintenance information for a Service Instance which is provisioned using this Service Plan.
maintenance_info.version semver Maintenance information about the version of this Service Plan. This field is used to determine whether a maintenance update is available for a Service Instance.
maintenance_info.description string Description of the impact of this maintenance update, for example, important version changes, configuration changes, default value changes, etc.
broker_catalog object This object contains information obtained from the Service Broker Catalog.
broker_catalog.id string The identifier that the Service Broker provided for this Service Plan.
broker_catalog.metadata object Additional information provided by the Service Broker.
broker_catalog.maximum_polling_duration integer The maximum number of seconds that Cloud Foundry will wait for an asynchronous Service Broker operation.
broker_catalog.features.plan_updateable boolean Whether the Service Plan supports upgrade/downgrade for Service Plans by default
broker_catalog.features.bindable boolean Specifies whether Service Instances of the service can be bound to applications.
schemas object Schema definitions for Service Instances and Service Bindings for the Service Plan.
schemas.service_instance.create object Schema definition for Service Instance creation.
schemas.service_instance.create.parameters JSON Schema object The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object.
schemas.service_instance.update object Schema definition for Service Instance update.
schemas.service_instance.update.parameters JSON Schema object The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object.
schemas.service_binding.create object Schema definition for Service Binding creation.
schemas.service_binding.create.parameters JSON Schema object The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object.
relationships.service_offering to-one relationship The Service Offering that this Service Plan relates to.
relationships.space to-one relationship The Space of the Service Broker, if this Service Plan is from a Space-Scoped Service Broker.
metadata.labels (experimental) label object Labels applied to the Service Plan.
metadata.annotations (experimental) annotation object Annotations added to the Service Plan.
links links object Links to related resources.

Get a Service Plan

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

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_big_service_plan",
  "description": "Big",
  "visibility_type": "public",
  "available": true,
  "free": false,
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "maintenance_info": {
    "version": "1.0.0+dev4",
    "description": "Database version 7.8.0"
  },
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "custom-key": "custom-information"
    },
    "maximum_polling_duration": null,
    "features": {
      "plan_updateable": true,
      "bindable": true
    }
  },
  "schemas": {
    "service_instance": {
      "create": {
        "parameters": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "billing-account": {
              "description": "Billing account number used to charge use of shared fake server.",
              "type": "string"
            }
          }
        }
      },
      "update": {}
    },
    "service_binding": {
      "create": {}
    }
  },
  "relationships": {
    "service_offering": {
      "data": {
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
    },
    "service_offering": {
      "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    },
    "visibility": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
    }
  }
}


This endpoint retrieves the service plan by GUID.

Definition

GET /v3/service_plans/:guid

Permitted roles

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

List service plans

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_plans?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_plans?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_plans?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
      "name": "my_big_service_plan",
      "description": "Big plan",
      "visibility_type": "organization",
      "available": true,
      "free": false,
      "created_at": "2019-11-28T13:44:02Z",
      "updated_at": "2019-11-28T13:44:02Z",
      "maintenance_info": {
        "version": "1.0.0+dev4",
        "description": "Database version 7.8.0"
      },
      "broker_catalog": {
        "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
        "metadata": {
          "custom-key": "custom-value"
        },
        "maximum_polling_duration": null,
        "features": {
          "plan_updateable": true,
          "bindable": true
        }
      },
      "schemas": {
        "service_instance": {
          "create": {
            "parameters": {
              "$schema": "http://json-schema.org/draft-04/schema#",
              "type": "object",
              "properties": {
                "billing-account": {
                  "description": "Billing account number used to charge use of shared fake server.",
                  "type": "string"
                }
              }
            }
          },
          "update": {}
        },
        "service_binding": {
          "create": {}
        }
      },
      "relationships": {
        "service_offering": {
          "data": {
            "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
        },
        "service_offering": {
          "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
        },
        "visibility": {
          "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
        }
      }
    },
    {
      "guid": "20e6cd62-12bb-11ea-90d1-7bfec2c75bcd",
      "name": "other_service_plan",
      "description": "Provides another service plan",
      "visibility_type": "admin",
      "available": true,
      "free": false,
      "created_at": "2019-11-29T16:44:02Z",
      "updated_at": "2019-11-29T16:44:02Z",
      "maintenance_info": {},
      "broker_catalog": {
        "id": "3cb11822-12bb-11ea-beb1-a350dc7453b9",
        "metadata": {
          "other-data": true
        },
        "maximum_polling_duration": null,
        "features": {
          "plan_updateable": true,
          "bindable": true
        }
      },
      "schemas": {
        "service_instance": {
          "create": {},
          "update": {}
        },
        "service_binding": {
          "create": {}
        }
      },
      "relationships": {
        "service_offering": {
          "data": {
            "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_plans/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
        },
        "service_offering": {
          "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
        },
        "visibility": {
          "href": "https://api.example.org/v3/service_plans/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd/visibility"
        }
      }
    }
  ]
}

This endpoint retrieves the service plans the user has access to.

Definition

GET /v3/service_plans

Query parameters

Name Type Description
names list of strings Comma-delimited list of names to filter by.
available boolean Filter by the available property. Valid values are true or false.
broker_catalog_id list of strings Comma-delimited list of IDs provided by the Service Broker for the Service Plan to filter by.
space_guids list of strings Comma-delimited list of Space GUIDs to filter by.
organization_guids list of strings Comma-delimited list of Organization GUIDs to filter by.
service_broker_guids list of strings Comma-delimited list of Service Broker GUIDs to filter by.
service_broker_names list of strings Comma-delimited list of Service Broker names to filter by.
service_offering_guids list of strings Comma-delimited list of Service Offering GUIDs to filter by.
service_offering_names list of strings Comma-delimited list of Service Offering names to filter by.
service_instance_guids list of strings Comma-delimited list of Service Instance GUIDs to filter by.
label_selector string Experimental - A query string containing a list of label selector requirements.

The organization_guids and space_guids filters do not filter plans that are public. They both act on plans that are restricted to certain Organizations, and to plans from Space-Scoped Service Brokers.

Permitted roles

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

Update a service plan

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

{
  "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
  "name": "my_big_service_plan",
  "description": "Big",
  "visibility_type": "public",
  "available": true,
  "free": false,
  "created_at": "2019-11-28T13:44:02Z",
  "updated_at": "2019-11-28T13:44:02Z",
  "maintenance_info": {
    "version": "1.0.0+dev4",
    "description": "Database version 7.8.0"
  },
  "broker_catalog": {
    "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
    "metadata": {
      "custom-key": "custom-information"
    },
    "maximum_polling_duration": null,
    "features": {
      "plan_updateable": true,
      "bindable": true
    }
  },
  "schemas": {
    "service_instance": {
      "create": {
        "parameters": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "billing-account": {
              "description": "Billing account number used to charge use of shared fake server.",
              "type": "string"
            }
          }
        }
      },
      "update": {}
    },
    "service_binding": {
      "create": {}
    }
  },
  "relationships": {
    "service_offering": {
      "data": {
        "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
      }
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
    },
    "service_offering": {
      "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
    },
    "visibility": {
      "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
    }
  }
}


This endpoint updates a Service Plan with labels and annotations.

Definition

PATCH /v3/service_plans/[guid]

Optional parameters

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

Permitted roles

Admin
Space Developer (only for service plans from space-scoped brokers)

Delete a Service Plan

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

This endpoint deletes a Service Plan. This is used to remove Service Plans from the Cloud Foundry database when they have are no longer provided by the Service Broker.

Definition

DELETE /v3/service_plans/:guid

Permitted roles

Admin
Space Developer (only service plans from space-scoped brokers)

Service Plan Visibility

Service Plan Visibility is used to manage whether a role has access to a given Service Plan and its Service Offering.

The Service Plan Visibility object

Example Service Plan Visibility object - Organization restricted
{
  "type": "organization",
  "organizations": [
    {
      "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
      "name": "my_org"
    }
  ]
}

Example Service Plan Visibility object - Space restricted
{
  "type": "space",
  "space": {
    "guid": "ab7eb420-11e5-11ea-b7db-4b5d5e7975ad",
    "name": "my_space"
  }
}

Name Type Description
type string Denotes the visibility of the plan. Can be public, admin, organization, space. See list of visibility types.
space.guid string Unique identifier for the space whose members can access the plan. Present if type is space.
space.name string Name of the space whose members can access the plan. Present if type is space.
organizations array of organization object List of organizations whose members can access the plan. Present if type is organization.

The organization visibility object

Name Type Description
guid string Unique identifier for the organization where the plan is available.
name string Name of the organization where the plan is available.

List of visibility types

Name Description
public Everyone, including unauthenticated users can see the Service Plan.
admin Only Admin, Admin Read-Only and Global Auditor can see the Service Plan.
organization Restricted to members of a set of Organizations.
space Restricted to members of a Space. Only possible if the Plan comes from a space-scoped Service Broker.

Get a Service Plan Visibility

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

{
  "type": "public"
}

This endpoint retrieves the service plan visibility for a given plan.

Definition

GET /v3/service_plans/:guid/visibility

Permitted roles

All Roles

Update a Service Plan Visibility

Example Request
curl "https://api.example.org/v3/service_plans/[guid]/visibility" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "organization",
    "organizations": [
      { "guid" : "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482" }
    ]
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "organization",
  "organizations": [
    {
      "guid": "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482",
      "name": "other_org"
    }
  ]
}

This endpoint updates a Service Plan Visibility. It behaves similar to the POST Service Plan Visibility endpoint but this endpoint will replace the existing list of organizations when the Service Plan is organization visible.

Definition

PATCH /v3/service_plans/[guid]/visibility

Parameters

Name Type Description
type string Denotes the visibility of the plan. Can be public, admin, organization. See list of visibility types.
organizations array of objects Desired list of organizations GUIDs where the plan will be accessible. Required if type is organization.

Permitted roles

Admin

Apply a Service Plan Visibility

Example Request
curl "https://api.example.org/v3/service_plans/[guid]/visibility" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "organization",
    "organizations": [
      { "guid": "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482" }
    ]
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "organization",
  "organizations": [
    {
      "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
      "name": "my_org"
    },
    {
      "guid": "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482",
      "name": "other_org"
    }
  ]
}

This endpoint applies a Service Plan Visibility. It behaves similar to the PATCH Service Plan Visibility endpoint but this endpoint will append to the existing list of organizations when the Service Plan is organization visible.

Definition

POST /v3/service_plans/[guid]/visibility

Parameters

Name Type Description
type string Denotes the visibility of the plan. Can be public, admin, organization. See list of visibility types.
organizations array of objects Desired list of organizations GUIDs where the plan will be accessible. Required if type is organization.

Permitted roles

Admin

Remove Organization from a Service Plan Visibility

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

This endpoint removes an Organization from a Service Plan Visibility list of Organizations. It is only defined for Service Plans which are org-restricted. It will fail with a HTTP Status Code of 422 for any other visibility type (e.g. Public).

Definition

DELETE /v3/service_plans/[guid]/visibility/[organization_guid]

Permitted roles

Admin

Sidecars

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

Use cases for sidecars

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

Steps to create a sidecar

The recommended way to create sidecars for your app is with an app manifest.

 sidecars:
  - name: authenticator
    process_types: [ 'web', 'worker' ]
    command: bundle exec run-authenticator
  - name: performance monitor
      process_types: [ 'web' ]
      command: bundle exec run-performance-monitor
      memory: 128M

1 Applies for Java apps. If you do not reserve memory for the sidecar, the JVM will consume all of the memory in the app container. This value must be less thatn the process’ reserved memory.

Current limitations

The sidecar object

Example Sidecar object
{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "origin": "user",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Name Type Description
guid uuid Unique identifier for the sidecar.
name string Human-readable name for the sidecar.
command string The command used to start the sidecar.
process_types array of strings A list of process types the sidecar applies to.
memory_in_mb integer Reserved memory for sidecar.
origin string Specifies whether the sidecar was created by the user or via the buildpack.
relationships.app to-one relationship The app the sidecar is associated with.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.

Create a sidecar associated with an app

Example Request
curl "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/sidecars" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "auth-sidecar",
    "command": "bundle exec rackup",
    "process_types": ["web", "worker"],
    "memory_in_mb": 300
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "origin": "user",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

POST /v3/apps/:guid/sidecars

Required parameters

Name Type Description
name string Human-readable name for the sidecar.
command string The command used to start the sidecar.
process_types array of strings A list of process types the sidecar applies to.

Optional parameters

Name Type Description
memory_in_mb integer Reserved memory for sidecar.

Permitted roles

Admin
Space Developer

Get a sidecar

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

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "origin": "user",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

GET /v3/sidecars/:guid

Permitted roles

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

Update a sidecar

Example Request
curl "https://api.example.org/v3/sidecars/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auth-sidecar",
    "command": "bundle exec rackup",
    "process_types": ["web", "worker"],
    "memory_in_mb": 300
  }'

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

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "origin": "user",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

PATCH /v3/sidecars/:guid

Optional parameters

Name Type Description
name string Human-readable name for the sidecar.
command string The command used to start the sidecar.
process_types array of strings A list of process types the sidecar applies to.
memory_in_mb integer Reserved memory for sidecar.

Permitted roles

Admin
Space Developer

List sidecars for app

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "name": "auth-sidecar",
      "command": "bundle exec rackup",
      "process_types": ["web", "worker"],
      "memory_in_mb": 300,
      "origin": "user",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z"
    },
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
      "name": "echo-sidecar",
      "command": "start-echo-server",
      "process_types": ["web"],
      "memory_in_mb": 300,
      "origin": "user",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:59Z",
      "updated_at": "2017-02-01T01:33:59Z"
    }
  ]
}

Retrieves all sidecars associated with a app.

Definition

GET /v3/apps/:guid/sidecars

Query parameters

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

Permitted roles

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

List sidecars for process

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

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "name": "auth-sidecar",
      "command": "bundle exec rackup",
      "process_types": ["web", "worker"],
      "memory_in_mb": 300,
      "origin": "user",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z"
    },
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
      "name": "echo-sidecar",
      "command": "start-echo-server",
      "process_types": ["web"],
      "memory_in_mb": 300,
      "origin": "user",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:59Z",
      "updated_at": "2017-02-01T01:33:59Z"
    }
  ]
}

Retrieves all sidecars associated with a process.

Definition

GET /v3/processes/:guid/sidecars

Query parameters

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

Permitted roles

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

Delete a sidecar

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

Definition

DELETE /v3/sidecars/:guid

Permitted roles

Admin
Space Developer

Space Manifest

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

The space manifest specification

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

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

Space-level configuration

Field Description
applications An array of App configurations

App-level configuration

This configuration is specified at the top-level and applies to all of the app’s processes.

Field Description
buildpacks Must be an Array.
a) An empty array, which will automatically select the appropriate default buildpack according to the coding language.
b) An array of one or more URLs pointing to buildpacks.
c) An array of one or more installed buildpack names.
Replaces the legacy buildpack field.
docker If present, the created app will have Docker lifecycle type. The value of this key is ignored by the API but may be used by clients to source the registry address of the image and credentials, if needed. The generate manifest endpoint will return the registry address of the image and username provided with this key.
env A key-value hash of environment variables to be used for the app when running.
no-route Boolean value. When set to true, any routes specified with the routes attribute will be ignored and any existing routes will be removed; ignored if false.
processes List of configurations for individual process types. See Process-level configuration.
random-route Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified.
default-route Boolean value. If true, a route for the app will be created using the app name as the hostname and the containing organization’s default domain as the domain. If false, if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored and results in noop.
routes An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path
services An array of service-instances to bind to the app. See Service-level configuration.
sidecars An array of configurations for individual sidecars. See Sidecar-level configuration.
stack The root filesystem to use with the buildpack, for example cflinuxfs3.
metadata.labels (experimental) Labels applied to the app.
metadata.annotations (experimental) Annotations applied to the app.
buildpack DEPRECATED in favor of the buildpacks field above.
a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language.
b) A URL pointing to a buildpack.
c) Name of an installed buildpack.

Process-level configuration

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

With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.

If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.

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

Service-level configuration

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

Field Description
name (Required) Service instance name. The name of the service instance to be bound to.
parameters A map of arbitrary key/value pairs to send to the service broker during binding.

Sidecar-level configuration

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

Field Description
name (Required) Sidecar name. The identifier for the sidecars to be configured.
command The command used to start the sidecar.
process_types List of processes to associate sidecar with.
memory Memory in mb that the sidecar will be allocated.

Apply a space manifest

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

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

Definition

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

Permitted roles

Admin
Space Developer

Upgrade Guide

This document is intended to help client authors upgrade from Cloud Foundry’s V2 API to the V3 API.

When moving to the V3 API, it is important to understand that the V3 API is backed by the same data as the V2 API. Though resources may be presented differently and have different interaction patterns, the internal state of CF will be the same across both APIs.

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

Changed Resources

This table shows how V2 resources map to their respective V3 counterparts. Note that some V2 resources have split into multiple V3 resources, and some V2 resources have been combined into a single resource on V3. As these resources are currently under active development, these mappings may change.

V2 Resource(s) V3 Resource(s) Details
Apps Apps, Builds, Droplets, Packages, Processes
Buildpacks Buildpacks
Domains, Shared Domains, Private Domains Domains Domains in V3
Environment Variable Groups Environment Variable Groups
Events Audit Events
Feature Flags Feature Flags
Jobs Jobs
Organizations Organizations
Quota Definitions Organization Quotas Organization Quotas in V3
Resource Matches Resource Matches
Routes, Route Mappings Routes Routes in V3
Security Groups Security Groups
Service Bindings, Service Keys Service Keys
Service Brokers Service Brokers
Service Instances, User-Provided Service Instances Service Instances
Spaces Spaces
Space Quota Definitions Space Quotas Space Quotas in V3
Stacks Stacks
Usage Events Usage Events
Users Roles, Users Users and Roles in V3

Domains in V3

In V2, there were two types of domains exposed via different endpoints: private domains and shared domains.

In V3, there is only one domain resource. A domain is “shared” if it has an “owning organization”, which is the organization in which the domain is accessible. This is represented as a relationship to this organization. A domain is “private” if it doesn’t have this relationship.

Read more about the domain resource.

Organization Quotas in V3

In V2, -1 represented an unlimited value for a quota limit.

In V3, null is used to represent an unlimited value.

The names of the limit fields have changed from V2 to V3.

V2 V3
non_basic_services_allowed services.paid_services_allowed
total_services services.total_service_instances
total_service_keys services.total_service_keys
total_routes routes.total_routes
total_reserved_route_ports routes.total_reserved_ports
total_private_domains domains.total_domains
memory_limit apps.total_memory_in_mb
instance_memory_limit apps.per_process_memory_in_mb
app_instance_limit apps.total_instances
app_task_limit apps.per_app_tasks

Read more about the organization quota resource.

Routes in V3

In V2, the route resource represented a URL that could be mapped to an app, and the route mapping resource represented a mapping between a route and an app.

In V3, these concepts have been collapsed into a single route resource. Now, a route can have one or more “destinations” listed on it. These represent a mapping from the route to a resource that can serve traffic (e.g. a process of an app).

Read more about routes and destinations.

Space Quotas in V3

In V2, -1 represented an unlimited value for a quota limit.

In V3, null is used to represent an unlimited value.

The names of the limit fields have changed from V2 to V3.

V2 V3
non_basic_services_allowed services.paid_services_allowed
total_services services.total_service_instances
total_service_keys services.total_service_keys
total_routes routes.total_routes
total_reserved_route_ports routes.total_reserved_ports
memory_limit apps.total_memory_in_mb
instance_memory_limit apps.per_process_memory_in_mb
app_instance_limit apps.total_instances
app_task_limit apps.per_app_tasks

Read more about the space quota resource.

Users and Roles in V3

The user resource remains largely unchanged from the v2 API. On v2, GET /v2/users was restricted to admins, and other users needed to use nested endpoints (GET /v2/organizations/:guid/user and GET /v2/spaces/:guid/user) to view user resources. On v3, GET /v3/users is now available for all users, similar to other resources. Note that this does not change what user resources are visible.

In V2, roles were modeled as associations between organization and space endpoints. In V3, roles have a dedicated resource: /v3/roles. This has changed the manner in which roles are assigned. For example, in V2, to assign a user the org_manager role, one would PUT /v2/organizations/:org_guid/managers/:user_id. In V3, one would POST /v3/roles with the role type and relationships to the user and organization.

Read more about users and roles.

Conceptual Changes

App Sub-Resources

The V2 API rolls up several resources into its representation of an “app”:

  1. Packages: Source assets for the application
  2. Droplets: Staged, executable assets for the application
  3. Builds: Configuration for how to stage the package into a droplet
  4. Processes: Configuration for how to run the droplet

The V3 API exposes these resources on the API to provide more visibility and enable more complicated workflows. For example:

  1. Staging a previous package into a new droplet
  2. Rolling back to a previous droplet
  3. Staging a droplet to run a task, without running any processes
  4. Running multiple different processes from a single droplet (for example: a web process and a worker process)

Here are some examples of implications for clients:

  1. The app resource contains much less information about the application as a whole
  2. An application can have multiple processes, each with their own start command, scale, and stats
  3. An application might not be running with its most recent package or droplet

Asynchronous Operations

Unlike V2, clients cannot opt-in for asynchronous responses from endpoints. Instead, endpoints that require asynchronous processing will return 202 Accepted with a Location header pointing to the job resource to poll. Endpoints that do not require asynchronous processing will respond synchronously.

For clients that want to report the outcome of an asynchronous operation, the expected pattern is to poll the job in the Location header until its state is no longer PROCESSING. If the job’s state is FAILED, the errors field will contain any errors that occurred during the operation.

An example of an asynchronous endpoint is the delete app endpoint.

Read more about the job resource.

Errors

Example Request
curl "https://api.example.org/v2/apps/not-found" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json

{
   "description": "The app could not be found: not-found",
   "error_code": "CF-AppNotFound",
   "code": 100004
}
Example Request
curl "https://api.example.org/v3/apps/not-found" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json

{
   "errors": [
      {
         "detail": "App not found",
         "title": "CF-ResourceNotFound",
         "code": 10010
      }
   ]
}

The V3 API returns an array of errors instead of a single error like in V2.

Clients may wish to display all returned errors.

Filtering

Filters are specified as individual query parameters in V3
curl "https://api.example.org/v2/apps?q=name+IN+dora,broker;stack:cflinuxfs3" \
  -X GET \
  -H "Authorization: bearer [token]"
curl "https://api.example.org/v3/apps?names=dora,broker&stacks=cflinuxfs3" \
  -X GET \
  -H "Authorization: bearer [token]"

Filtering resources no longer uses V2’s query syntax. See the example to the right.

A few common filters have been also renamed in V3:

V2 filter V3 filter
results-per-page per_page
page page
order-by order_by
order-direction N/A1

1 In V3, order is ascending by default. Prefix the order_by value with - to make it descending. For example, ?order_by=-name would order a list of resources by name in descending order.

Read more about filtering in V3.

Including Associated Resources

The inline-relations-depth parameter is no longer supported on V3. Instead, some resources support the include parameter to selectively include associated resources in the response body.

For example, to include an app’s space in the response: cf curl /v3/apps/:guid?include=space

Read more about the include parameter.

New Concepts

Actions

Actions are API requests that are expected to immediately initiate change within the Cloud Foundry runtime. This is differentiated from requests which update a record but require additional updates, such as restarting an app, to cause changes to a resource to take effect.

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

Example Request
curl "https://api.example.org/v3/apps/:guid" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
{
  "...": "...",
  "links": {
    "self": {
      "href": "http://api.example.com/v3/apps/:guid"
    },
    "space": {
      "href": "http://api.example.com/v3/spaces/:space_guid"
    }
  }
}

Links provide URLs to associated resources, relationships, and actions for a resource. The example links to both the app itself and the space in which it resides.

Metadata

Example Request
curl "https://api.example.org/v3/:resource/:guid" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
{
  "...": "...",
  "metadata": {
    "labels": {
      "environment": "production",
      "internet-facing": "false"
    },
    "annotations": {
      "contacts": "Bill tel(1111111) email(bill@fixme)"
    }
  }
}

Metadata allows you to tag and query certain API resources with information; metadata does not affect the resource’s functionality.

For more details and usage examples, see metadata or official CF docs.

Note that metadata consists of two keys, labels and annotations, each of which consists of key-value pairs. API V3 allows filtering by labels (see label_selector) but not by annotations.

Relationships

Example Request
curl "https://api.example.org/v3/apps" \
  -X POST \
  -H "Authorization: bearer [token]"
  -d '{
        "name": "testapp",
        "relationships": {
         "space": { "data": { "guid": "1234" }}
        }
      }'

Relationships represent associations between resources: For example, every space belongs in an organization, and every app belongs in a space. The V3 API can create, read, update, and delete these associations.

In the example request we create an app with a relationship to a specific space.

One can retrieve or update a resource’s relationships. For example, to retrieve an app’s relationship to its space with the /v3/apps/:app_guid/relationships/space endpoint.

For more information, refer to the relationships.

New Resources

The V3 API introduces new resources that are not available on the V2 API. Below are brief descriptions of these resources. This is not intended to be an exhaustive list and may not be updated as new resources are added to V3.

Note: Some of these resources may still be experimental and are subject to change or removal without warning. For up to date information on which resources are still experimental see Experimental Resources.

App Features

App features support enabling/disabling behaviors for an individual app.

Read more about the app feature resource.

Deployments

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

Read more about the deployment resource.

Isolation Segments

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

Read more about the isolation segment resource.

Manifests

Manifests are a method for providing bulk configuration to applications and other resources in a space.

Read more about the app manifest and space manifest resources.

Revisions

Revisions represent code and configuration used by an application at a specific time. The most recent revision for a running application represents the code and configuration currently running in Cloud Foundry.

Read more about the revision resource.

Sidecars

Sidecars are additional programs that are run in the same container as a process.

Read more about the sidecar resource.

Tasks

Tasks are one-off jobs that are intended to execute a droplet, stop, and be cleaned up, freeing up resources.

Examples of this include database migrations and running batch jobs.

Read more about the task resource.

  1. V3 API Proposals
  2. CAPI (Cloud Controller API) Slack Channel