+ Introduction
+ +Overview
+ +Welcome to the Cloud Foundry V3 API docs! Version 3 adds support for several +key features:
+ +-
+
- Running one-off tasks on Cloud Foundry +
- Applications consisting of several processes via a Procfile +
- Direct access to application packages and droplets +
- Changing application source code without stopping the app via deployments +
Getting help
+ +The CAPI team can most easily be reached on our Slack channel for +questions and issues regarding the API. To report an issue with the docs or API, please feel free to file a GitHub +issue on our API repo, cloud_controller_ng.
+ +We recommend reaching out to Slack first as we will be most responsive there.
+ +More resources
+ +-
+
- The Cloud Foundry V2 API is still available for interacting with Cloud Foundry. +
- Running Tasks +
- V3 API Documentation Source Code +
Concepts
+API Resource
+ +A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object.
+ +A resource consists of several required resource fields and other attributes specific to the resource.
+ +See Resources and Experimental Resources for specific resources.
+ +Required fields
+Example Person Resource
+{
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+
+ "name": "Bob",
+
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ }
+ }
+}
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +The unique identifier for the resource | +
| created_at | +timestamp | +The ISO8601 compatible date and time when resource was created | +
| updated_at | +timestamp | +The ISO8601 compatible date and time when resource was last updated | +
| links | +links object | +URLs to related resources and actions for the current resource | +
Links
+ +Links provide URLs to relationships and actions for a resource. Links are represented as a JSON object and always contain a self link.
Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET.
The link object
+Example Link object
+{
+ "href": "http://example.com/some/endpoint",
+ "method": "POST"
+}
+| Name | +Type | +Description | +
|---|---|---|
| href | +string | +The absolute URL | +
| method | +string | +An optional field containing the HTTP method to be used when following the URL | +
Authentication
+ +The Cloud Foundry V3 API is secured using OAuth 2. Clients are expected to present a valid bearer token via HTTP header: Authorization: bearer <token>
Tokens can be obtained from the Cloud Foundry UAA server. For more information, see the UAA API Documentation
+ + +Authorization
+ +Access to resources is determined by combining scopes in the OAuth 2 token with user roles that are managed by the API.
+ +OAuth 2 scopes
+ +| Scope | +Description | +
|---|---|
cloud_controller.admin |
+This scope provides read and write access to all resources | +
cloud_controller.admin_read_only |
+This scope provides read only access to all resources | +
cloud_controller.global_auditor |
+This scope provides read only access to all resources except secrets (such as environment variables) | +
cloud_controller.read |
+This scope provides read access to resources based on user roles | +
cloud_controller.write |
+This scope provides write access to resources based on user roles | +
cloud_controller.update_build_state |
+This scope allows its bearer to update the state of a build; currently only used when updating builds | +
cloud_controller_service_permissions.read |
+This scope provides read only access for service instance permissions | +
Cloud Foundry user roles
+ +Users that interact with the API should have one or more of these roles. Some of them (e.g. admin) +are controlled via scopes on the user’s token. Others (e.g. space developer) are controlled via the +roles resource.
+ +| Role | +Description | +
|---|---|
| Admin | +Allows a user to manage the platform; OAuth token must contain cloud_controller.admin scope |
+
| Admin Read-Only | +Allows a user to read all resources on the platform; OAuth token must contain cloud_controller.admin_read_only scope |
+
| Global Auditor | +Allows a user to read all resources on the platform, excluding sensitive data such as environment variables and service bindings. OAuth token must contain cloud_controller.global_auditor scope |
+
| Org User | +Allows a user to be assigned other roles within an organization and its spaces | +
| Org Manager | +Provides organization management access | +
| Org Auditor | +Provides read-only access to an organization for auditing purposes | +
| Org Billing Manager | +Allows a user to create and manage billing account and payment information | +
| Space Developer | +Allows developers to create and manage apps and services in a space | +
| Space Manager | +Provides space management access | +
| Space Auditor | +Provides read-only access to a space for auditing purposes | +
| Space Supporter | +Troubleshoot and debug apps and service bindings in a space | +
Component roles
+ +Components that interact with the Cloud Controller in the back-end can be given these roles to allow +limited access to API resources. These roles are controlled via scopes on the component’s token.
+ +| Role | +Description | +
|---|---|
| Build State Updater | +Allows a component to update the state of build resources; OAuth token must contain cloud_controller.update_build_state scope |
+
Errors
+Example Error
+{
+ "errors": [
+ {
+ "code": 10008,
+ "title": "CF-UnprocessableEntity",
+ "detail": "something went wrong"
+ }
+ ]
+}
+An error response will always return a list of error objects. Errors appear on the job resource for asynchronous operations.
+ +The error object
+ +Clients should use the code and title fields for programmatically handling specific errors.
+The message in the detail field is subject to change over time.
| Name | +Type | +Description | +
|---|---|---|
| code | +integer | +A numeric code for this error | +
| title | +string | +Name of the error | +
| detail | +string | +Detailed description of the error | +
Common errors
+ +These are some of the more common errors returned by many endpoints.
+ +| Title | +Code | +HTTP Status | +Description | +
|---|---|---|---|
CF-BadQueryParameter |
+10005 | +400 | +An invalid query parameter was given | +
CF-InvalidAuthToken |
+1000 | +401 | +An invalid auth token was given | +
CF-NotAuthenticated |
+10002 | +401 | +No auth token was given, but authentication is required for this endpoint | +
CF-NotAuthorized |
+10003 | +403 | +The authenticated user does not have permission to perform this operation | +
CF-ResourceNotFound |
+10010 | +404 | +The specified resource does not exist, or the authenticated user cannot read it | +
CF-UnprocessableEntity |
+10008 | +422 | +Catch-all error when an operation fails to complete; the detail field will contain more information |
+
UnknownError |
+10001 | +500 | +An unexpected, uncaught error occurred; the CC logs will contain more information | +
Fields
+ +The fields parameter allows clients to fetch resources and include information of parent objects
+in the response. It works in a similar way to include, but the response only displays
+the requested fields rather than the entire resource.
For example, a response to /v3/service_instances/:guid?fields[space.organization]=name will contain detailed
+information about the service instance, as well as the name of the organization it belongs to.
Developers may choose to use the fields feature to reduce the number of API calls. The fields
+query param can be used with a single resource or a list of resources.
The fields query parameter may also grant visibility to parts of resources where the whole resource is not visible. +For instance, the name of an organization may be retrieved with fields, where the whole organization resource may +not be visible.
+ +Fields parameter
+ +The fields parameter is structured as: fields[resource]=keys&fields[parent.resource]=other,keys
-
+
resourceis the name of the resource being requested, qualified by the relationship to the current resource. +For example/v3/service_instances?fields[space]=namewherespaceis a direct relationship of a service instance, +or/v3/service_instances?fields[space.organization]=namewhereorganizationis a relationship ofspace.
+keysis a comma-separated list of the fields in the object being requested. For example, +/v3/service_instances?fields[space]=name,guidwill return just thenameandguidof the space in the includes section.
+
For information on fields support for each resource refer to its documentation.
Resources with Fields
+ +| Resource | +Endpoint | +
|---|---|
| Service Instances | +v3/service_instances, v3/service_instances/:guid | +
| Shared Spaces | +/v3/service_instances/:guid/relationships/shared_spaces | +
| Service Offerings | +v3/service_offerings, v3/service_offerings/:guid | +
| Service Plans | +v3/service_plans, v3/service_plans/:guid | +
Fields Sample requests
+Example request to service instances resource to include parent orgs and spaces
+curl "https://api.example.org/v3/service_instances?fields[space]=name,guid,relationships.organization&fields[space.organization]=name,guid" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example response
+{
+ "pagination": {
+ "total_results": 2,
+ "...": "..."
+ },
+ "resources": [
+ {
+ "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
+ "name": "service_instance_1",
+ "...": "..."
+ },
+ {
+ "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
+ "name": "service_instance_2",
+ "...": "..."
+ }
+ ],
+ "included": {
+ "spaces": [
+ {
+ "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
+ "name": "space1",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "b2075a71-28b6-411a-a896-56f75d892f58"
+ }
+ }
+ }
+ },
+ {
+ "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
+ "name": "space2",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "b56fbd01-296b-442b-8faf-a559aebf985e"
+ }
+ }
+ }
+ }
+ ],
+ "organizations": [
+ {
+ "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
+ "name": "org1"
+ },
+ {
+ "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
+ "name": "org2"
+ }
+ ]
+ }
+}
+Filters
+ +Endpoints which return lists of resources also support filtering the returned resources using query parameters. Each +resource’s list endpoint documents the allowed filters for that endpoint. For details about the syntax of query parameters +in general, see query parameters.
+ +Examples
+ +Single value request
+ +GET /v3/apps?names=the_name
This will return all apps with name the_name.
Multiple value request
+ +GET /v3/apps?names=first_name,second_name
This will return all apps with name the_name OR second_name.
In the case of audit events, multiple timestamps can be requested, which will return all audit +events that occurred at those timestamps. In the following request, all audit events that occurred +New Year’s just before midnight and July 4th at noon will be returned:
+ +GET /v3/audit_events?created_ats=2019-12-31T23:59:59Z,2020-07-04T12:00:00Z
Exception
+ +The label_selector query parameter will act as AND function, not an OR.
GET /v3/spaces?label_selector=production,east_coast
This will return all spaces whose metadata has labels with keys production AND east_coast.
Combined filters
+ +GET /v3/apps?names=the_name&stacks=cflinuxfs4
This will return all apps with name the_name AND stack cflinuxfs4.
Empty filters
+ +An empty filter (/v3/resources?fields=) can mean either empty string ("") or NULL, depending on the resource type.
GET /v3/buildpacks?stacks=
This will return all buildpacks with stack NULL.
GET /v3/routes?hosts=hostname1,,hostname2
This will return all routes with hostname "hostname1", "" OR "hostname2".
Relational Operators
+ +Some fields (e.g. created_at and updated_at) can be filtered using relational operators when listing resources.
For example, a response to GET /v3/audit_events?created_ats[lt]=2020-06-30T12:34:56Z will contain
+audit events with a created_at timestamp strictly earlier than 2020-06-30T12:34:56Z.
Multiple relational operators can be combined to further refine the listed resources. For example, a
+response to GET /v3/audit_events?created_ats[lt]=2020-01-02T00:00:00Z&created_ats[gt]=2019-12-31T23:59:59Z
+will return all audit events occurring on New Year’s Day.
Timestamps must be in standard timestamp format.
+ +Valid relational operators
+ +| Operator | +Description | +
|---|---|
| lt | +Return resources strictly less than the given value for the filtered attribute | +
| lte | +Return resources less than or equal to the given value for the filtered attribute | +
| gt | +Return resources strictly greater than the given value for the filtered attribute | +
| gte | +Return resources greater than or equal to the given value for the filtered attribute | +
Exclusion Operator
+ +Some fields support filtering on all values except a given set of values.
+ +For example, a response to GET /v3/audit_events?target_guids[not]=guid-1,guid-2
+will contain audit events with a target.guid not equal to guid-1 nor guid-2.
| Operator | +Description | +
|---|---|
| not | +Return resources not equal to the given value(s) for the filtered attribute | +
Include
+ +The include parameter allows clients to fetch resources and include information of parent objects in the response.
+For example, a response to /v3/spaces/:guid?include=organization will contain detailed information about the space and its parent organization.
Developers may choose to use the include feature to reduce the number of API calls. The include
+query param can be used with a single resource or a list of resources.
Resources with includes
+ +The following resources can take an include parameter:
| Resource | +Allowed values | +
|---|---|
| apps | +space.organization, space |
+
| apps/[:guid] | +space.organization, space |
+
| roles | +user, space, organization |
+
| roles/[:guid] | +user, space, organization |
+
| routes | +domain, space.organization, space |
+
| routes/[:guid] | +domain, space.organization, space |
+
| service_plans | +space.organization, service_offering |
+
| service_plans/[:guid] | +space.organization, service_offering |
+
| service_credential_bindings | +app, service_instance |
+
| service_credential_bindings/[:guid] | +app, service_instance |
+
| service_route_bindings | +route, service_instance |
+
| service_route_bindings/[:guid] | +route, service_instance |
+
| spaces | +organization |
+
| spaces/[:guid] | +organization |
+
Sample requests
+Example request to apps resource to include parent orgs and spaces
+curl "https://api.example.org/v3/apps?include=space.organization" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example response
+{
+ "pagination": {
+ "total_results": 2,
+ "...": "..."
+ },
+ "resources": [
+ {
+ "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
+ "name": "app1",
+ "...": "..."
+ },
+ {
+ "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
+ "name": "app2",
+ "...": "..."
+ }
+ ],
+ "included": {
+ "spaces": [
+ {
+ "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
+ "name": "space1",
+ "...": "..."
+ },
+ {
+ "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
+ "name": "space2",
+ "...": "..."
+ }
+ ],
+ "organizations": [
+ {
+ "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
+ "name": "org1",
+ "...": "..."
+ },
+ {
+ "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
+ "name": "org2",
+ "...": "..."
+ }
+ ]
+ }
+}
+Example request for a single app instance to include its parent space
+curl "https://api.example.org/v3/apps/[guid]?include=space" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example response
+{
+ "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
+ "name": "staticfile",
+ "...": "...",
+ "included": {
+ "spaces": [
+ {
+ "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
+ "name": "space1a",
+ "...": "..."
+ }
+ ]
+ }
+}
+Lifecycles
+ +Lifecycles inform the platform of how to build droplets and run apps. For example, a docker lifecycle will
+pull a Docker image from a registry to run an app.
The lifecycle object
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Type of the lifecycle; valid values are buildpack, cnb, docker |
+
| data | +object | +Data that is used during staging and running for a lifecycle | +
Buildpack lifecycle
+Example Buildpack Lifecycle
+{
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+}
+This is the default lifecycle for Cloud Foundry for VMs. When staging an app with this lifecycle, the app source code will be +compiled using a buildpack, resulting in a droplet. When running an app with this lifecycle, a container running a rootfs +will be created and the droplet will be expanded inside that container to be executed.
+ +If buildpacks are not specified, then Cloud Foundry will automatically detect a +compatible buildpack, based on the files in an app’s package. If a stack is not +specified, then the app will default to the operator-configured default stack.
+ +Buildpack lifecycle object
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +buildpack |
+
| data.buildpacks | +list of strings | +A list of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack during staging |
+
| data.stack | +string | +The root filesystem to use with the buildpack, for example cflinuxfs4 |
+
Cloud Native Buildpacks Lifecycle (experimental)
+Example Cloud Native Buildpacks lifecycle
+{
+ "type": "cnb",
+ "data": {
+ "buildpacks": [
+ "docker://example.org/java-buildpack:latest"
+ "docker://second-example.org/logging-buildpack:latest"
+ ],
+ "stack": "cflinuxfs4",
+ "credentials": {
+ "example.org": {
+ "username": "user",
+ "password": "****"
+ },
+ "second-example.org": {
+ "token": "****"
+ },
+ }
+ }
+}
+This lifecycle allows Cloud Foundry to stage an application using the Cloud Native Buildpacks.
+ +Note: the data.buildpacks field is required (at least 1 buildpack must be set).
+ +Cloud Native Buildpacks lifecycle object
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +cnb |
+
| data.buildpacks | +list of strings | +A list of URLs with either docker:// or http(s):// scheme, pointing to the Cloud Native Buildpack OCI image. When the scheme is http(s)://, an OCI tarball is expected to be present at the specified location. |
+
| data.credentials | +object | +Credentials used to download the configured buildpacks. This can either contain username/password or a token. | +
| data.stack | +string | +The root filesystem to use with the buildpack, for example cflinuxfs4 |
+
Docker lifecycle
+Example Docker Lifecycle
+{
+ "type": "docker",
+ "data": {}
+}
+This allows Cloud Foundry to run pre-built Docker images. When staging an app with this lifecycle, the Docker registry is queried for +metadata about the image, such as ports and start command. When running an app with this lifecycle, a container is created +and the Docker image is executed inside of it.
+ +Docker lifecycle object
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +docker |
+
| data | +object | +Data is not used by the Docker lifecycle; valid value is {} |
+
Metadata
+ +Metadata allows you to tag API resources with information that does not directly affect its functionality.
+ +Annotations
+Example Resource with Annotations
+{
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "api-server",
+ "metadata": {
+ "labels": {},
+ "annotations": {
+ "contacts": "Bill tel(1111111) email(bill@fixme), Bob tel(222222) pager(3333333#555) email(bob@fixme)"
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ }
+ }
+}
+Annotations are user-specified key-value pairs that are attached to API resources. They do not affect the operation of Cloud Foundry. Annotations cannot be used in filters.
+ +When a service instance is being created, the service broker is sent the annotations of the service instance, and the space and organization in which the service instance resides.
+When a service instance is being updated, the service broker is sent the annotations of the space and organization in which the service instance resides.
+When a service binding is being created, the service broker is sent annotations of any associated app, and the space and organization in which the binding resides.
+Only annotations with a prefix (e.g. company.com/contacts) are sent to service brokers.
Examples may include (but are not limited to):
+ +-
+
"contact info": "bob@example.com jane@example.com"
+"library versions": "Spring: 5.1, Redis Client: a184098. yaml parser: 38"
+"git-sha": "d56fe0367554ae5e878e37ed6c5b9a82f5995512"
+
Annotation keys
+ +Annotation keys are made up of an (optional) prefix and name. If a prefix is present, it is separated from the name by a /.
+Prefixes are DNS names intended to enable namespacing of annotation keys.
An annotation key prefix must adhere to the following restrictions:
-
+
- Length: 0-253 characters +
- Allowed characters: a-z, A-Z, 0-9,
-, and.; emojis cannot be used in keys
+ - DNS subdomain format (series of subdomain annotations separated by
.)
+
An annotation key name must adhere to the following restrictions:
-
+
- Length: 1-63 characters +
- Allowed characters: a-z, A-Z, 0-9,
-,_, and.; emojis cannot be used in keys
+ - Must begin and end with an alphanumeric character +
Annotation values
+ +Annotation values must adhere to the following restrictions:
+ +-
+
- Length: 0-5000 unicode characters +
Labels and selectors
+Example Resource with Labels
+{
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "api-server",
+ "metadata": {
+ "labels": {
+ "environment": "production",
+ "internet-facing": "false"
+ },
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ }
+ }
+}
+Labels are user-specified key/value pairs that are attached to API Resources. +They are queryable, identifying attributes of a resource, but they do not affect the operation of CloudFoundry.
+ +For example, an app may be assigned a label with key sensitive and possible values true or false.
Users could then find all sensitive apps with a selector for sensitive=true, resulting in a response containing
+only apps having the label key sensitive with a label value of true.
Labels
+ +Labels allow users to apply identifying attributes to resources that are meaningful to the user, but not the CloudFoundry system.
+ +Examples may include (but are not limited to):
+ +-
+
"production" : "true"or"production" : "false"
+"env" : "dev"or"env" : "test"or"env" : "prod"
+"chargeback-code" : "abc123"
+
Label keys
+ +Label keys are made up of an (optional) prefix, and name. If a prefix is present, it is separated from the name by a /.
+Prefixes are dns names intended to enable namespacing of label keys.
A label key prefix must adhere to the following restrictions:
-
+
- Length: 0-253 characters +
- Allowed characters: alphanumeric ( [a-z0-9A-Z] ),
-, and.
+ - DNS subdomain format (series of subdomain labels separated by
.)
+
A label key name must adhere to the following restrictions:
-
+
- Length: 1-63 characters +
- Allowed characters: alphanumeric ( [a-z0-9A-Z] ),
-,_, and.
+ - Must begin and end with an alphanumeric character +
Label values
+ +Label values must adhere to the following restrictions:
+ +-
+
- Length: 0-63 characters +
- Allowed characters: alphanumeric ( [a-z0-9A-Z] ),
-,_, and.
+ - Must begin and end with an alphanumeric character +
- Empty values are allowed +
Selectors
+Example label selector
+cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29
+Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or
+more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.
eg: env=dev,!chargeback-code,tier in (backend,worker)
Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.
A requirement consists of a key, an operator, and optional value(s).
| Requirement | +Format | +Description | +
|---|---|---|
| existence | +key | +Returns all resources that have been assigned a label with the given key (with any value) | +
| non-existence | +!key |
+Returns all resources that have not been assigned a label with the given key (with any value) | +
| equality | +key=value or key==value |
+Returns all resources that have been assigned a label with the given key and value | +
| inequality | +key!=value |
+Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value | +
| set inclusion | +key in (value1,value2…) |
+Returns all resources that have been assigned a label with the given key with one of the specified value(s) | +
| set exclusion | +key notin (value1,value2…) |
+Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s) | +
See the metadata documentation for more information.
+ +Updating labels and annotations
+Example Initial Metadata
+{
+ "metadata": {
+ "labels": {
+ "environment": "staging",
+ "ready-to-deploy": "true"
+ },
+ "annotations": {
+ "spring-version": "5.1",
+ "app-version": "0.1-alpha"
+ }
+ }
+}
+Example Patch Request Body
+{
+ "metadata": {
+ "labels": {
+ "environment": "production",
+ "ready-to-deploy": null
+ },
+ "annotations": {
+ "app-version": "0.1",
+ "deployed-month": "november"
+ }
+ }
+}
+Example Final Metadata
+{
+ "metadata": {
+ "labels": {
+ "environment": "production"
+ },
+ "annotations": {
+ "spring-version": "5.1",
+ "app-version": "0.1",
+ "deployed-month": "november"
+ }
+ }
+}
+Labels and annotations can be updated by using the PATCH endpoint for their resource. +For example, to update labels or annotations on an app, use the update an app endpoint. +When patching metadata, CAPI endpoints do a deep merge, only updating labels or annotations that are specified in the request.
+ +Labels and annotations follow the same rules for patching and must be wrapped in the metadata object inside the request body
+ +-
+
- To create, include the new key with a value +
- To change, include the existing key with a new value +
- To delete, include the existing key with a
nullvalue
+ - To remain unchanged, do not include the existing key. +
Pagination
+Example Paginated Response
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 3,
+ "first": {
+ "href": "https://api.example.org/v3/people?page=1&per_page=1"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/people?page=3&per_page=1"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/people?page=2&per_page=1"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "Bob",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ }
+ }
+ }
+ ]
+}
+Any request that can return multiple resources will be paginated and contain a pagination object and list of resources.
+Requests for multiple resources can use page, per_page, and order_by in addition to filters specific to the endpoint.
The pagination object
+ +| Name | +Type | +Description | +
|---|---|---|
| total_results | +integer | +Total number of resources for all pages | +
| total_pages | +integer | +Total number of pages | +
| first | +link object | +Link to the first page | +
| last | +link object | +Link to the last page | +
| next | +link object | +Link to the next page | +
| previous | +link object | +Link to the previous page | +
Procfiles
+Example Ruby Procfile
+web: bundle exec rackup config.ru -p $PORT
+rake: bundle exec rake
+worker: bundle exec rake workers:start
+A Procfile enables you to declare required runtime processes, called process types, for your app.
+Procfiles must be named Procfile exactly and placed in the root directory of your application.
In a Procfile, you declare one process type per line and use the syntax PROCESS_TYPE: COMMAND.
-
+
PROCESS_TYPEdefines the type of the process.
+COMMANDis the command line to launch the process.
+
Procfile use cases
+ +Many buildpacks provide their own process types and commands by default; however, there are special
+cases where specifying a custom COMMAND is necessary. Commands can be overwritten by providing a
+Procfile with the same process type.
For example, a buildpack may provide a worker process type that runs the rake default:start
+command. If a Procfile is provided that also contains a worker process type, but a different
+command such as rake custom:start, the rake custom:start command will be used.
Some buildpacks, such as Python, that work on a variety of frameworks, do not attempt to provide a +default start command. For these cases, a Procfile should be used to specify any necessary commands +for the app.
+ +Web process
+ +web is a special process type that is required for all applications.
+The web PROCESS_TYPE must be specified by either the buildpack or the Procfile.
Specifying processes in manifest files
+ +Custom process types can also be configured via a manifest file. Read more about +manifests. It is not recommended to specify processes in both a manifest and a +Procfile for the same app.
+Query Parameters
+ +Clients can assume that query parameters on the API will always follow these rules:
+ +-
+
- Parameter names (before the
=, and ignoring any modifiers like[gt]) will only contain charactersa-z(lowercase) and-.
+ - When a parameter accepts multiple values, these will be represented as a comma-delimited list of strings (see filters). +
Because commas are used to separate list entries, parameter values that contain commas must be percent-encoded. For example, to retrieve apps named either a,b or c,d, the query parameter would look like names=a%2Cb,c%2Cd. Note that the commas within the app names are encoded (as %2C), but the comma separating the two app names is not. The resulting query parameter must be encoded a second time before sending it to the API, e.g. cf curl /v3/apps?names=a%252Cb,c%252Cd.
Relationships
+ +Relationships represent associations between resources. When relationships are mutable, they can be +used to create, read, update, and delete these associations. An app’s relationship to its current +droplet is mutable, but an app’s relationship to its space is not.
+ +Relationships do not affect the fundamental properties of a resource, but may affect their behavior +and permissions logic. Relationships are tied to the lifecycles of the associated resources and +will be removed if either of the associated resources are deleted. For example, if a user is removed +from an organization, both the user and the organization persist, but the relationship between them +does not.
+ +Not all resources implement every relationship operation demonstrated in the examples below. See the +docs for each resource to see how it interacts with its relationships.
+ +Endpoints that return relationship data list this information under the relationships key.
The relationship object
+ +The relationship object is a key-value pair that uniquely identifies a resource. In practice this is
+almost always the guid of a resource.
| Name | +Type | +Description | +
|---|---|---|
| guid | +string | +The unique identifier for the related resource | +
To-one relationships
+Example to-one relationship
+{
+ "data": {
+ "guid": "[related-resource-guid]"
+ }
+}
+Some relationships relate a resource to exactly one other resource. For example an app can belong to +only one space.
+ +To-one relationship object
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +relationship object | +A single relationship | +
Setting the to-one relationship while creating an object
+curl "https://api.example.org/v3/books" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "color": "yellow",
+ "relationships": {
+ "publisher": {
+ "data": {
+ "guid": "publisher-guid"
+ }
+ }
+ }
+ }'
+Modifying the to-one relationship
+curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": {
+ "guid": "publisher-guid"
+ }
+ }'
+Removing the to-one relationship
+curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{ "data": null }'
+Viewing the to-one relationship
+curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+To-many relationships
+Example to-many relationship
+{
+ "data": [
+ { "guid": "[related-resource-guid-1]" },
+ { "guid": "[related-resource-guid-2]" }
+ ]
+}
+Some relationships relate a resource to several other resources. For example, an isolation segment can be entitled to multiple organizations.
+ +To-many relationship object
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +array of relationship objects | +An array of multiple relationships | +
Adding related to-many resources
+curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": [
+ { "guid":"author-guid-1" },
+ { "guid":"author-guid-2" }
+ ]
+ }'
+Replacing all to-many relationships
+curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": [
+ { "guid":"author-guid-3" },
+ { "guid":"author-guid-4" }
+ ]
+ }'
+Removing all to-many relationships
+curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{ "data": [] }'
+Removing specific to-many relationships
+curl "https://api.example.org/v3/books/[guid]/relationships/authors/[author-guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Viewing the to-many relationships
+curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Status Codes
+ +Cloud Foundry V3 API uses a subset of HTTP response codes to indicate the success or failure of an API request. +In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that can potentially be fixed by correcting the request, and codes in the 5xx range indicate an error on the server side.
+ +| HTTP Status Code | +Description | +
|---|---|
| 200 OK | +The request completed successfully | +
| 201 Created | +The request completed successfully and created a new resource | +
| 202 Accepted | +The request will be completed asynchronously; see asynchronous operations | +
| 204 No Content | +The request completed successfully and did not return a body | +
| 400 Bad Request | +The request has malformed or invalid data | +
| 401 Unauthenticated | +The request requires an authenticated user | +
| 403 Forbidden | +The request cannot be performed by the user | +
| 404 Not Found | +The requested resource does not exist | +
| 422 Unprocessable Entity | +The request cannot be performed | +
| 500 Internal Server Error | +An unexpected error occurred | +
| 502 Bad Gateway | +An external upstream service caused the request to fail | +
| 503 Service Unavailable | +An internal upstream service caused the request to fail | +
Timestamps
+ +Timestamps generally appear in created_at and updated_at fields on resources. Precision beyond
+seconds is not supported, even if the underlying database supports it (e.g. Postgres). As a result,
+filtering on sub-second timestamps is not allowed.
All v3 timestamps have the following format YYYY-MM-DDThh:mm:ssZ.
Example timestamp (June 30, 2020 at 11:49:04 PM UTC): 2020-06-30T23:49:04Z
Updating Actual State
+ +The Cloud Controller is primarily responsible for the desired state of apps and processes. Most endpoints will +only update the desired states of your apps and processes within Cloud Controller in order +to provide users with the opportunity to incur zero downtime when updating apps. Restarting +the app will be required for the desired state changes to become the actual state.
+ +The stats endpoint can be used at any time to determine the actual +(running) state of a process, and by proxy, an app.
+ +Endpoints that will affect runtime
+ +The following endpoints will immediately impact the runtime of the app, and the desired changes will take effect without needing to restart the app.
+ +| Endpoint | +
|---|
PATCH /v3/spaces/:guid/features/ssh |
+
DELETE /v3/routes/:guid/destinations/:destination_guid |
+
The following endpoints will immediately impact runtime and take effect when only the instances field is updated. If any other fields are updated, the app will need to be restarted in order for any desired changes to take effect, including instance count changes.
| Endpoint | +
|---|
POST /v3/processes/:guid/actions/scale |
+
POST /v3/apps/:guid/processes/:type/actions/scale |
+
The following endpoints will immediately impact runtime and the desired changes will take effect if the specified fields are not included in the request.
+ +If the field is specified, the app will need to be restarted in order for any desired changes to take effect.
+ +| Endpoint | +Changes requiring a restart | +
|---|---|
POST /v3/routes/:guid/destinations |
+Adding a destination with a port | +
PATCH /v3/routes/:guid/destinations |
+Replacing the port field Note: If the port is specified, this endpoint will unmap any route not listed in the body but will not map any of the new routes in the request body. For this reason we caution against using the endpoint in most circumstances. A combination of adding ports and removing ports will better fit most use cases. |
+
All other changes will not take effect on running apps until they are restarted.
+Warnings
+Example Warnings
+{
+ "warnings": [
+ {
+ "detail": "something went wrong"
+ }
+ ]
+}
+Warnings appear on the job resource.
+ +The warning object
+ +| Name | +Type | +Description | +
|---|---|---|
| detail | +string | +Description of the warning | +
Resources
+Admin
+ +These endpoints are only for admin users.
+Clear buildpack cache
+Example Request
+curl "https://api.example.org/v3/admin/actions/clear_buildpack_cache" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+This endpoint will delete all of the existing buildpack caches in the +blobstore. The buildpack cache is used during staging by buildpacks as a way to +cache certain resources, e.g. downloaded Ruby gems. An admin who wants to +decrease the size of their blobstore could use this endpoint to delete +unnecessary blobs.
+ +Definition
+ +POST /v3/admin/actions/clear_buildpack_cache
Permitted roles
+ +| + |
|---|
| Admin | +
Apps
+ +Apps are top-level objects that link together and contain configuration +information for your packages, droplets, processes, tasks, and more.
+The app object
+Example App object
+{
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STOPPED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the app | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the app | +
| state | +string | +Current desired state of the app; valid values are STOPPED or STARTED |
+
| lifecycle | +lifecycle object | +Provides the default lifecycle object for the application. This lifecycle will be used when staging and running the application. The staging lifecycle can be overridden on builds | +
| relationships.space | +to-one relationship | +The space the app is contained in | +
| relationships.current_droplet | +to-one relationship | +The current droplet used by the application | +
| metadata.labels | +label object | +Labels applied to the app | +
| metadata.annotations | +annotation object | +Annotations added to the app | +
| links | +links object | +Links to related resources | +
Create an app
+Example Request
+curl "https://api.example.org/v3/apps" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my_app",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STOPPED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +POST /v3/apps
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the app | +
| relationships.space | +to-one relationship | +A relationship to a space | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| environment_variables | +object | +Environment variables to be used for the App when running | +{} |
+
| lifecycle | +lifecycle object | +Provides the lifecycle object for the application | +buildpack lifecycle | +
| metadata.labels | +label object | +Labels applied to the app | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the app | ++ |
Potential errors (experimental)
+ +In addition to any common errors, this endpoint may return the following errors.
+ +| Title | +Code | +HTTP Status | +Description | +
|---|---|---|---|
CF-UniquenessError |
+10016 | +422 | +The given app name is already taken in the targeted space | +
CF-FeatureDisabled |
+330002 | +403 | +Some feature flag must be enabled by the Cloud Foundry admin in order to push the app as is. The detail message should contain information on which feature is disabled. |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Get an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STOPPED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +GET /v3/apps/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| include | +list of strings | +Optionally include additional related resources in the response; valid values are space and space.organization |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List apps
+Example Request
+curl "https://api.example.org/v3/apps" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/apps?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/apps?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STARTED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-03-18T11:32:30Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "02b4ec9b-94c7-4468-9c23-4e906191a0f8",
+ "name": "my_app2",
+ "state": "STOPPED",
+ "created_at": "1970-01-01T00:00:02Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["ruby_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+ }
+
+Retrieve all apps the user has access to.
+ +Definition
+ +GET /v3/apps
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| names | +list of strings | +Comma-delimited list of app names to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| stacks | +list of strings | +Comma-delimited list of stack names to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 | +
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at, name, state |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| lifecycle_type | +string | +Lifecycle type to filter by; valid values are buildpack, cnb, docker |
+
| include | +list of strings | +Optionally include a list of unique related resources in the response; valid values are space and space.organization |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Update an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my_app",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"]
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STARTED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-03-18T11:32:30Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +PATCH /v3/apps/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the app | +
| lifecycle | +lifecycle object | +Lifecycle to be used when updating the app; note: data is a required field in lifecycle if lifecycle is updated |
+
| metadata.labels | +label object | +Labels applied to the app | +
| metadata.annotations | +annotation object | +Annotations applied to the app | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Delete an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/apps/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Get current droplet
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/droplets/current" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "execution_metadata": "",
+ "process_types": {
+ "rake": "bundle exec rake",
+ "web": "bundle exec rackup config.ru -p $PORT"
+ },
+ "checksum": {
+ "type": "sha256",
+ "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "buildpacks": [
+ {
+ "name": "ruby_buildpack",
+ "detect_output": "ruby 1.6.14",
+ "version": "1.1.1.",
+ "buildpack_name": "ruby"
+ }
+ ],
+ "stack": "cflinuxfs4",
+ "image": null,
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +GET /v3/apps/:guid/droplets/current
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Get current droplet association for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/relationships/current_droplet" \
+ -X GET \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": {
+ "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet"
+ },
+ "related": {
+ "href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/droplets/current"
+ }
+ }
+}
+
+This endpoint retrieves the current droplet relationship for an app.
+ +Definition
+ +GET /v3/apps/:guid/relationships/current_droplet
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Get environment for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/env" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "staging_env_json": {
+ "GEM_CACHE": "http://gem-cache.example.org"
+ },
+ "running_env_json": {
+ "HTTP_PROXY": "http://proxy.example.org"
+ },
+ "environment_variables": {
+ "RAILS_ENV": "production"
+ },
+ "system_env_json": {
+ "VCAP_SERVICES": {
+ "mysql": [
+ {
+ "name": "db-for-my-app",
+ "binding_id": "0e85b634-e043-4b43-96da-f83dfe83ab33",
+ "binding_name": "db-for-my-app",
+ "instance_id": "07fca01c-f789-4d45-80b4-e19ba3ca862c",
+ "instance_name": "my-mysql-service",
+ "label": "mysql",
+ "tags": ["relational", "sql"],
+ "plan": "xlarge",
+ "credentials": {
+ "username": "user",
+ "password": "top-secret"
+ },
+ "syslog_drain_url": "https://syslog.example.org/drain",
+ "volume_mounts": [],
+ "provider": null
+ }
+ ]
+ }
+ },
+ "application_env_json": {
+ "VCAP_APPLICATION": {
+ "limits": {
+ "fds": 16384
+ },
+ "application_name": "my_app",
+ "application_uris": [ "my_app.example.org" ],
+ "name": "my_app",
+ "space_name": "my_space",
+ "space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
+ "uris": [ "my_app.example.org" ],
+ "users": null
+ }
+ }
+}
+Retrieve the environment variables that will be provided to an app at runtime. +It will include environment variables for Environment Variable Groups and Service Bindings.
+ +Definition
+ +GET /v3/apps/:guid/env
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Space Developer | ++ |
| Space Supporter | +system_env_json redacted |
+
Get environment variables for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/environment_variables" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "var": {
+ "RAILS_ENV": "production"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/[guid]/environment_variables"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/[guid]"
+ }
+ }
+}
+Retrieve the environment variables that are associated with the given app. +For the entire list of environment variables that will be available to the app at runtime, see the env endpoint.
+ +Definition
+ +GET /v3/apps/:guid/environment_variables
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Space Developer | +
| Space Supporter | +
Get permissions for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/permissions" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "read_basic_data": true,
+ "read_sensitive_data": false
+}
+Get the current user’s permissions for the given app. If a user can see an app, +then they can see its basic data. Only admin, read-only admins, and space +developers can read sensitive data.
+ +Definition
+ +GET /v3/apps/:guid/permissions
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Set current droplet
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/relationships/current_droplet" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{ "data": { "guid": "[droplet_guid]" } }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": {
+ "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet"
+ },
+ "related": {
+ "href": "https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/droplets/current"
+ }
+ }
+}
+
+Set the current droplet for an app. The current droplet is the droplet that the app will use when running.
+ +Definition
+ +PATCH /v3/apps/:guid/relationships/current_droplet
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Get SSH enabled for an app
+Example Request
+curl "https://api.example.org/v3/apps/:guid/ssh_enabled" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "enabled": false,
+ "reason": "Disabled globally"
+}
+
+Returns if an application’s runtime environment will accept ssh connections.
+If ssh is disabled,
+the reason field will describe
+whether it is disabled globally, at the space level, or at the app level.
Definition
+ +GET /v3/apps/:guid/ssh_enabled
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Start an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/actions/start" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STARTED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-03-18T11:32:30Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +POST /v3/apps/:guid/actions/start
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Stop an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/actions/stop" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STOPPED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-03-18T11:32:30Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +POST /v3/apps/:guid/actions/stop
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Restart an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/actions/restart" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STARTED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-03-18T11:32:30Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+This endpoint will synchronously stop and start an application. +Unlike the start and stop actions, +this endpoint will error if the app is not successfully stopped +in the runtime.
+ +For restarting applications without downtime, see the deployments resource.
+ +Definition
+ +POST /v3/apps/:guid/actions/restart
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Clear buildpack cache for application
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/actions/clear_buildpack_cache" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+This endpoint will delete the buildpack cache for a specified app. +The buildpack cache is used during staging by buildpacks as a way to +cache certain resources, e.g. downloaded Ruby gems. A user may want to use this +endpoint when an app doesn’t stage anymore due to out-of-disk caused +by a large buildpack cache content.
+ +Definition
+ +POST /v3/apps/:guid/actions/clear_buildpack_cache
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Update environment variables for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/environment_variables" \
+ -X PATCH \
+ -H "Content-Type: application/json" \
+ -H "Authorization: bearer [token]" \
+ -d '{
+ "var": {
+ "DEBUG": "false",
+ "USER": null
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "var": {
+ "RAILS_ENV": "production",
+ "DEBUG": "false"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/[guid]/environment_variables"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/[guid]"
+ }
+ }
+}
+Update the environment variables associated with the given app.
+The variables given in the request will be merged with the existing app environment variables.
+Any requested variables with a value of null will be removed from the app.
+Environment variable names may not start with VCAP_. PORT is not a valid environment variable.
Definition
+ +PATCH /v3/apps/:guid/environment_variables
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
App Features
+ +App features are used to manage whether optional capabilities are enabled for a given application.
+The app feature object
+Example App Feature object
+{
+ "name": "ssh",
+ "description": "Enable SSHing into the app.",
+ "enabled": true
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the app feature | +
| description | +string | +Description of the app feature | +
| enabled | +boolean | +Denotes whether or not the app feature is enabled | +
Supported app features
+ +Note: SSH must also be enabled globally and on the space.
+ +| Name | +Description | +
|---|---|
| ssh | +Enable SSHing into the app | +
| revisions | +Enable versioning of an application | +
Get an app feature
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/features/[name]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "name": "ssh",
+ "description": "Enable SSHing into the app.",
+ "enabled": true
+}
+
+Definition
+ +GET /v3/apps/:guid/features/:name
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List app features
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/features" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "resources": [
+ {
+ "name": "ssh",
+ "description": "Enable SSHing into the app.",
+ "enabled": true
+ },
+ {
+ "name": "revisions",
+ "description": "Enable versioning of an application",
+ "enabled": false
+ }
+ ],
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
+ "last": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
+ "next": null,
+ "previous": null
+ }
+}
+
+This endpoint retrieves the list of features for the specified app.
+ +Definition
+ +GET /v3/apps/:guid/features
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update an app feature
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/features/[name]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{ "enabled": false }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "name": "ssh",
+ "description": "Enable SSHing into the app.",
+ "enabled": true
+}
+
+Definition
+ +PATCH /v3/apps/:guid/features/:name
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| enabled | +boolean | +Denotes whether or not the app feature should be enabled | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | ++ |
| Space Supporter | +Can only update revisions feature | +
App Usage Events
+ +App usage events are a record of changes in the usage of apps and tasks. +Examples include starting an application, scaling an application (from, say, one +to three instances), and stopping an application.
+ +Usage events are typically used by billing and chargeback applications.
+The app usage event object
+Example App Usage Event object
+{
+ "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
+ "created_at": "2020-05-28T16:41:23Z",
+ "updated_at": "2020-05-28T16:41:26Z",
+ "state": {
+ "current": "STARTED",
+ "previous": "STOPPED"
+ },
+ "app": {
+ "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
+ "name": "name-1982"
+ },
+ "process": {
+ "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
+ "type": "type-1983"
+ },
+ "space": {
+ "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
+ "name": "name-1664"
+ },
+ "organization": {
+ "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
+ },
+ "buildpack": {
+ "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
+ "name": "label-64"
+ },
+ "task": {
+ "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
+ "name": "name-2929"
+ },
+ "memory_in_mb_per_instance": {
+ "current": 512,
+ "previous": 256
+ },
+ "instance_count": {
+ "current": 10,
+ "previous": 5
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the event | +
| created_at | +timestamp | +The time with zone when the event occurred | +
| updated_at | +timestamp | +Identical to created_at (events are created, never updated) |
+
| state.current | +string or null |
+Current state of the app that this event pertains to, if applicable | +
| state.previous | +string or null |
+Previous state of the app that this event pertains to, if applicable | +
| app.guid | +string or null |
+Unique identifier of the app that this event pertains to, if applicable | +
| app.name | +string or null |
+Name of the app that this event pertains to, if applicable | +
| process.guid | +string or null |
+Unique identifier of the process that this event pertains to, if applicable | +
| process.type | +string or null |
+Type of the process that this event pertains to, if applicable | +
| space.guid | +string or null |
+Unique identifier of the space that this event pertains to, if applicable | +
| space.name | +string or null |
+Name of the space that this event pertains to, if applicable | +
| organization.guid | +string or null |
+Unique identifier of the org that this event pertains to, if applicable | +
| buildpack.guid | +string or null |
+Unique identifier of the buildpack that this event pertains to, if applicable | +
| buildpack.name | +string or null |
+Name of the buildpack that this event pertains to, if applicable | +
| task.guid | +string or null |
+Unique identifier of the task that this event pertains to, if applicable | +
| task.name | +string or null |
+Name of the task that this event pertains to, if applicable | +
| memory_in_mb_per_instance.current | +integer or null |
+Current memory in MB of the app that this event pertains to, if applicable | +
| memory_in_mb_per_instance.previous | +integer or null |
+Previous memory in MB of the app that this event pertains to, if applicable | +
| instance_count.current | +integer or null |
+Current instance count of the app that this event pertains to, if applicable | +
| instance_count.previous | +integer or null |
+Previous instance count of the app that this event pertains to, if applicable | +
| links | +links object | +Links to related resources | +
Get an app usage event
+Example Request
+curl "https://api.example.org/v3/app_usage_events/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
+ "created_at": "2020-05-28T16:41:23Z",
+ "updated_at": "2020-05-28T16:41:26Z",
+ "state": {
+ "current": "STARTED",
+ "previous": "STOPPED"
+ },
+ "app": {
+ "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
+ "name": "name-1982"
+ },
+ "process": {
+ "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
+ "type": "type-1983"
+ },
+ "space": {
+ "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
+ "name": "name-1664"
+ },
+ "organization": {
+ "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
+ },
+ "buildpack": {
+ "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
+ "name": "label-64"
+ },
+ "task": {
+ "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
+ "name": "name-2929"
+ },
+ "memory_in_mb_per_instance": {
+ "current": 512,
+ "previous": 256
+ },
+ "instance_count": {
+ "current": 10,
+ "previous": 5
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
+ }
+ }
+}
+
+Retrieve an app usage event.
+ +Definition
+ +GET /v3/app_usage_events/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
List app usage events
+Example Request
+curl "https://api.example.org/v3/app_usage_events" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/app_usage_events?page=1&per_page=1"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/app_usage_events?page=2&per_page=1"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/app_usage_events?page=2&per_page=1"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
+ "created_at": "2020-05-28T16:41:23Z",
+ "updated_at": "2020-05-28T16:41:26Z",
+ "state": {
+ "current": "STARTED",
+ "previous": "STOPPED"
+ },
+ "app": {
+ "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
+ "name": "name-1982"
+ },
+ "process": {
+ "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
+ "type": "type-1983"
+ },
+ "space": {
+ "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
+ "name": "name-1664"
+ },
+ "organization": {
+ "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
+ },
+ "buildpack": {
+ "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
+ "name": "label-64"
+ },
+ "task": {
+ "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
+ "name": "name-2929"
+ },
+ "memory_in_mb_per_instance": {
+ "current": 512,
+ "previous": 256
+ },
+ "instance_count": {
+ "current": 10,
+ "previous": 5
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all app usage events the user has access to.
+ +Definition
+ +GET /v3/app_usage_events
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid value is created_at |
+
| after_guid | +string | +Filters out events before and including the event with the given guid | +
| guids | +list of strings | +Comma-delimited list of usage event guids to filter by | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Purge and seed app usage events
+Example Request
+curl "https://api.example.org/v3/app_usage_events/actions/destructively_purge_all_and_reseed" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+Destroys all existing events. Populates new usage events, one for each started app. All populated events will have a created_at value of current time. There is the potential race condition if apps are currently being started, stopped, or scaled. The seeded usage events will have the same guid as the app.
Definition
+ +POST /v3/app_usage_events/actions/destructively_purge_all_and_reseed
Permitted roles
+ +| + |
|---|
| Admin | +
Audit Events
+ +Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions.
+ +For more information, see the Cloud Foundry docs.
+ +Audit Event Types
+ +App lifecycle
+ +-
+
audit.app.apply_manifest
+audit.app.build.create
+audit.app.copy-bits
+audit.app.create
+audit.app.delete-request
+audit.app.deployment.cancel
+audit.app.deployment.create
+audit.app.deployment.continue
+audit.app.droplet.create
+audit.app.droplet.delete
+audit.app.droplet.download
+audit.app.droplet.mapped
+audit.app.droplet.upload
+audit.app.environment.show
+audit.app.environment_variables.show
+audit.app.map-route
+audit.app.package.create
+audit.app.package.delete
+audit.app.package.download
+audit.app.package.upload
+audit.app.process.crash
+audit.app.process.create
+audit.app.process.delete
+audit.app.process.ready
+audit.app.process.not-ready
+audit.app.process.rescheduling
+audit.app.process.scale
+audit.app.process.terminate_instance
+audit.app.process.update
+audit.app.restage
+audit.app.restart
+audit.app.revision.create
+audit.app.revision.environment_variables.show
+audit.app.ssh-authorized
+audit.app.ssh-unauthorized
+audit.app.start
+audit.app.stop
+audit.app.task.cancel
+audit.app.task.create
+audit.app.unmap-route
+audit.app.update
+audit.app.upload-bits
+
Organization lifecycle
+ +-
+
audit.organization.create
+audit.organization.delete-request
+audit.organization.update
+
Route lifecycle
+ +-
+
audit.route.create
+audit.route.delete-request
+audit.route.share
+audit.route.transfer-owner
+audit.route.unshare
+audit.route.update
+
Service lifecycle
+ +-
+
audit.service.create
+audit.service.delete
+audit.service.update
+
Service_binding lifecycle
+ +-
+
audit.service_binding.create
+audit.service_binding.delete
+audit.service_binding.show
+audit.service_binding.start_create
+audit.service_binding.start_delete
+audit.service_binding.update
+
Service_broker lifecycle
+ +-
+
audit.service_broker.create
+audit.service_broker.delete
+audit.service_broker.update
+
Service_dashboard_client lifecycle
+ +-
+
audit.service_dashboard_client.create
+audit.service_dashboard_client.delete
+
Service_instance lifecycle
+ +-
+
audit.service_instance.bind_route
+audit.service_instance.create
+audit.service_instance.delete
+audit.service_instance.purge
+audit.service_instance.share
+audit.service_instance.show
+audit.service_instance.start_create
+audit.service_instance.start_delete
+audit.service_instance.start_update
+audit.service_instance.unbind_route
+audit.service_instance.unshare
+audit.service_instance.update
+
Service_key lifecycle
+ +-
+
audit.service_key.create
+audit.service_key.delete
+audit.service_key.show
+audit.service_key.start_create
+audit.service_key.start_delete
+audit.service_key.update
+
Service_plan lifecycle
+ +-
+
audit.service_plan.create
+audit.service_plan.delete
+audit.service_plan.update
+
Service_plan_visibility lifecycle
+ +-
+
audit.service_plan_visibility.create
+audit.service_plan_visibility.delete
+audit.service_plan_visibility.update
+
Service_route_binding lifecycle
+ +-
+
audit.service_route_binding.create
+audit.service_route_binding.delete
+audit.service_route_binding.start_create
+audit.service_route_binding.start_delete
+audit.service_route_binding.update
+
Space lifecycle
+ +-
+
audit.space.create
+audit.space.delete-request
+audit.space.update
+
User lifecycle
+ +-
+
audit.user.organization_auditor_add
+audit.user.organization_auditor_remove
+audit.user.organization_billing_manager_add
+audit.user.organization_billing_manager_remove
+audit.user.organization_manager_add
+audit.user.organization_manager_remove
+audit.user.organization_user_add
+audit.user.organization_user_remove
+audit.user.space_auditor_add
+audit.user.space_auditor_remove
+audit.user.space_developer_add
+audit.user.space_developer_remove
+audit.user.space_manager_add
+audit.user.space_manager_remove
+audit.user.space_supporter_add
+audit.user.space_supporter_remove
+
User_provided_service_instance lifecycle
+ +-
+
audit.user_provided_service_instance.create
+audit.user_provided_service_instance.delete
+audit.user_provided_service_instance.show
+audit.user_provided_service_instance.update
+
Special events
+ +-
+
app.crash
+blob.remove_orphan
+
The audit event object
+Example Audit Event object
+{
+ "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
+ "created_at": "2016-06-08T16:41:23Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "type": "audit.app.update",
+ "actor": {
+ "guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
+ "type": "user",
+ "name": "admin"
+ },
+ "target": {
+ "guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
+ "type": "app",
+ "name": "my-app"
+ },
+ "data": {
+ "request": {
+ "recursive": true
+ }
+ },
+ "space": {
+ "guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
+ },
+ "organization": {
+ "guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the event | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| type | +string | +The type of the event | +
| actor.guid | +string | +Unique identifier for the actor (user or system resource that performed the action) | +
| actor.type | +string | +The actor type | +
| actor.name | +string | +The name of the actor | +
| target.guid | +uuid | +Unique identifier for the target (resource that the event acted upon) | +
| target.type | +string | +The target type | +
| target.name | +string | +The name of the target | +
| data | +object | +Additional information about event | +
| space.guid | +uuid | +Unique identifier for the space where the event occurred; if the event did not occur within a space, the space field will be null |
+
| organization.guid | +uuid | +Unique identifier for the organization where the event occurred; if the event did not occur within an organization, the organization field will be null |
+
| links | +links object | +Links to related resources | +
Get an audit event
+Example Request
+curl "https://api.example.org/v3/audit_events/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
+ "created_at": "2016-06-08T16:41:23Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "type": "audit.app.update",
+ "actor": {
+ "guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
+ "type": "user",
+ "name": "admin"
+ },
+ "target": {
+ "guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
+ "type": "app",
+ "name": "my-app"
+ },
+ "data": {
+ "request": {
+ "recursive": true
+ }
+ },
+ "space": {
+ "guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
+ },
+ "organization": {
+ "guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
+ }
+ }
+}
+
+Definition
+ +GET /v3/audit_events/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Auditor | +Cannot see events which occurred in orgs that the user does not belong to | +
| Space Auditor | +Cannot see events which occurred in spaces that the user does not belong to | +
| Space Developer | +Cannot see events which occurred in spaces that the user does not belong to | +
| Space Supporter | +Cannot see events which occurred in spaces that the user does not belong to | +
List audit events
+Example Request
+curl "https://api.example.org/v3/audit_events" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/audit_events?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/audit_events?page=1&per_page=2"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
+ "created_at": "2016-06-08T16:41:23Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "type": "audit.app.update",
+ "actor": {
+ "guid": "d144abe3-3d7b-40d4-b63f-2584798d3ee5",
+ "type": "user",
+ "name": "admin"
+ },
+ "target": {
+ "guid": "2e3151ba-9a63-4345-9c5b-6d8c238f4e55",
+ "type": "app",
+ "name": "my-app"
+ },
+ "data": {
+ "request": {
+ "recursive": true
+ }
+ },
+ "space": {
+ "guid": "cb97dd25-d4f7-4185-9e6f-ad6e585c207c"
+ },
+ "organization": {
+ "guid": "d9be96f5-ea8f-4549-923f-bec882e32e3c"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org//v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all audit events the user has access to.
+ +Definition
+ +GET /v3/audit_events
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| types | +list of strings | +Comma-delimited list of event types to filter by | +
| target_guids | +list of strings | +Comma-delimited list of target guids to filter by. Also supports filtering by exclusion. | +
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Builds
+ +Builds represent the process of staging an application package. There are two types +(lifecycles) of builds: buildpack and docker.
+ +After an application is created and packages are uploaded, a build +resource can be created to initiate the staging process. A successful build results in a +droplet.
+The build object
+Example Build object
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "created_by": {
+ "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
+ "name": "bill",
+ "email": "bill@example.com"
+ },
+ "state": "STAGED",
+ "staging_memory_in_mb": 1024,
+ "staging_disk_in_mb": 1024,
+ "staging_log_rate_limit_bytes_per_second": 1024,
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": [ "ruby_buildpack" ],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "package": {
+ "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
+ },
+ "droplet": {
+ "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the build | +
| created_at | +timestamp | +The time with zone when the build was created | +
| updated_at | +timestamp | +The time with zone when the build was last updated | +
| state | +string | +State of the build; valid states are STAGING, STAGED, or FAILED |
+
| staging_memory_in_mb | +integer | +Memory in MB allocated for staging of the build | +
| staging_disk_in_mb | +integer | +Disk space in MB allocated for staging of the build | +
| staging_log_rate_limit_bytes_per_second | +integer | +Log rate limit in bytes per second allocated for staging of the build | +
| error | +string | +A string describing errors during the build process | +
| lifecycle | +lifecycle object | +Provides the lifecycle object to use during staging; this will override the build’s application’s default lifecycle for this build | +
| package.guid | +string | +The package that is the input to the staging process | +
| droplet.guid | +string | +A resulting droplet from the staging process; droplet will be null if staging has not completed |
+
| created_by.guid | +object | +The guid of the user that created the build | +
| created_by.name | +object | +The name of the user that created the build | +
| created_by.email | +object | +The email of the user that created the build | +
| relationships.app | +to-one relationship | +The app the build belongs to | +
| metadata.labels | +label object | +Labels applied to the build | +
| metadata.annotations | +annotation object | +Annotations applied to the build | +
| links | +links object | +Links to related resources | +
Create a build
+Example Request
+curl "https://api.example.org/v3/builds" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "package": {
+ "guid": "[package-guid]"
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "created_by": {
+ "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
+ "name": "bill",
+ "email": "bill@example.com"
+ },
+ "state": "STAGING",
+ "staging_memory_in_mb": 1024,
+ "staging_disk_in_mb": 1024,
+ "staging_log_rate_limit_bytes_per_second": 1024,
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": [ "ruby_buildpack" ],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "package": {
+ "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
+ },
+ "droplet": null,
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+}
+
+Definition
+ +POST /v3/builds
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| package | +object | +App package to stage | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| lifecycle | +lifecycle object | +Lifecycle information for a build | +lifecycle on the app | +
| staging_memory_in_mb | +integer | +Memory in MB allocated for staging of the build | ++ |
| staging_disk_in_mb | +integer | +Disk space in MB allocated for staging of the build | ++ |
| staging_log_rate_limit_bytes_per_second | +integer | +Log rate limit in bytes per second allocated for staging of the build | ++ |
| metadata.labels | +label object | +Labels applied to the build | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the build | ++ |
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Get a build
+Example Request
+curl "https://api.example.org/v3/builds/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "created_by": {
+ "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
+ "name": "bill",
+ "email": "bill@example.com"
+ },
+ "state": "STAGED",
+ "staging_memory_in_mb": 1024,
+ "staging_disk_in_mb": 1024,
+ "staging_log_rate_limit_bytes_per_second": 1024,
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": [ "ruby_buildpack" ],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "package": {
+ "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
+ },
+ "droplet": {
+ "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
+ }
+ }
+}
+
+Definition
+ +GET /v3/builds/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List builds
+Example Request
+curl "https://api.example.org/v3/builds" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "created_by": {
+ "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
+ "name": "bill",
+ "email": "bill@example.com"
+ },
+ "state": "STAGING",
+ "staging_memory_in_mb": 1024,
+ "staging_disk_in_mb": 1024,
+ "staging_log_rate_limit_bytes_per_second": 1024,
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": [ "ruby_buildpack" ],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "package": {
+ "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
+ },
+ "droplet": null,
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all builds the user has access to.
+ +Definition
+ +GET /v3/builds
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| states | +list of strings | +Comma-delimited list of build states to filter by | +
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| package_guids | +list of strings | +Comma-delimited list of package guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List builds for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/builds" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/apps/[guid]/builds?states=STAGING&page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps/[guid]/builds?states=STAGING&page=1&per_page=2"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "created_by": {
+ "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
+ "name": "bill",
+ "email": "bill@example.com"
+ },
+ "state": "STAGING",
+ "staging_memory_in_mb": 1024,
+ "staging_disk_in_mb": 1024,
+ "staging_log_rate_limit_bytes_per_second": 1024,
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": [ "ruby_buildpack" ],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "package": {
+ "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
+ },
+ "droplet": null,
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all builds for the app.
+ +Definition
+ +GET /v3/apps/:guid/builds
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| states | +list of strings | +Comma-delimited list of build states to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update a build
+Example Request
+curl "https://api.example.org/v3/builds/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "created_by": {
+ "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
+ "name": "bill",
+ "email": "bill@example.com"
+ },
+ "state": "STAGED",
+ "staging_memory_in_mb": 1024,
+ "staging_disk_in_mb": 1024,
+ "staging_log_rate_limit_bytes_per_second": 1024,
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": [ "ruby_buildpack" ],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "package": {
+ "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
+ },
+ "droplet": {
+ "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/builds/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the build | +
| metadata.annotations | +annotation object | +Annotations applied to the build | +
| state | +string | +Build status; valid values are FAILED or STAGED (field can only be passed by Build State Updaters) |
+
| lifecycle.data.image | +string | +Image reference tag where the built complete image was stored (field can only be passed by Build State Updaters) | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | ++ |
| Build State Updater | +This is a special component role; read more about component roles | +
Buildpacks
+ +Buildpacks are used during a build +to download external dependencies +and transform a package +into an executable droplet. +In this way, buildpacks are a pluggable extension to Cloud Foundry +that enable CF to run different languages and frameworks. +Buildpacks will automatically detect if they support an application. +Buildpacks can also be explicitly specified on apps and builds.
+The buildpack object
+Example Buildpack object
+ {
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "ruby_buildpack",
+ "state": "AWAITING_UPLOAD",
+ "filename": null,
+ "stack": "windows64",
+ "position": 42,
+ "enabled": true,
+ "locked": false,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
+ "method": "POST"
+ }
+ }
+ }
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the buildpack | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +The name of the buildpack; to be used by app buildpack field (only alphanumeric characters) | +
| state | +string | +The state of the buildpack; valid states are: AWAITING_UPLOAD, READY |
+
| stack | +string | +The name of the stack that the buildpack will use | +
| filename | +string | +The filename of the buildpack | +
| position | +integer | +The order in which the buildpacks are checked during buildpack auto-detection | +
| enabled | +boolean | +Whether or not the buildpack can be used for staging | +
| locked | +boolean | +Whether or not the buildpack is locked to prevent updating the bits | +
| metadata.labels | +label object | +Labels applied to the app | +
| metadata.annotations | +annotation object | +Annotations added to the app | +
| links | +links object | +Links to related resources | +
Create a buildpack
+Example Request
+curl "https://api.example.org/v3/buildpacks" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "ruby_buildpack",
+ "position": 42,
+ "enabled": true,
+ "locked": false,
+ "stack": "windows64"
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+ {
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "ruby_buildpack",
+ "state": "AWAITING_UPLOAD",
+ "filename": null,
+ "stack": "windows64",
+ "position": 42,
+ "enabled": true,
+ "locked": false,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
+ "method": "POST"
+ }
+ }
+ }
+
+Definition
+ +POST /v3/buildpacks
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the buildpack | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| stack | +string | +The name of the stack that the buildpack will use | +null | +
| position | +integer | +The order in which the buildpacks are checked during buildpack auto-detection | +1 | +
| enabled | +boolean | +Whether or not the buildpack will be used for staging | +true | +
| locked | +boolean | +Whether or not the buildpack is locked to prevent updating the bits | +false | +
| metadata.labels | +label object | +Labels applied to the buildpack | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the buildpack | ++ |
Permitted roles
+ +| + |
|---|
| Admin | +
Get a buildpack
+Example Request
+curl "https://api.example.org/v3/buildpacks/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "ruby_buildpack",
+ "state": "AWAITING_UPLOAD",
+ "filename": null,
+ "stack": "windows64",
+ "position": 42,
+ "enabled": true,
+ "locked": false,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
+ "method": "POST"
+ }
+ }
+ }
+
+Definition
+ +GET /v3/buildpacks/:guid
Permitted roles
+ +| + |
|---|
| All Roles | +
List buildpacks
+Example Request
+curl "https://api.example.org/v3/buildpacks" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/buildpacks?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/buildpacks?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/buildpacks?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "my-buildpack",
+ "state": "AWAITING_UPLOAD",
+ "filename": null,
+ "stack": "my-stack",
+ "position": 1,
+ "enabled": true,
+ "locked": false,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
+ "method": "POST"
+ }
+ }
+ }
+ ]
+ }
+
+Retrieve all buildpacks the user has access to.
+ +Definition
+ +GET /v3/buildpacks
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| names | +list of strings | +Comma-delimited list of buildpack names to filter by | +
| stacks | +list of strings | +Comma-delimited list of stack names to filter by | +
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and position |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Update a buildpack
+Example Request
+curl "https://api.example.org/v3/buildpacks/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "ruby_buildpack",
+ "position": 42,
+ "enabled": true,
+ "locked": false,
+ "stack": "windows64"
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "ruby_buildpack",
+ "state": "AWAITING_UPLOAD",
+ "filename": null,
+ "stack": "windows64",
+ "position": 42,
+ "enabled": true,
+ "locked": false,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
+ "method": "POST"
+ }
+ }
+ }
+
+Definition
+ +PATCH /v3/buildpacks/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the buildpack | +
| stack | +string | +The name of the stack that the buildpack will use | +
| position | +integer | +The order in which the buildpacks are checked during buildpack auto-detection | +
| enabled | +boolean | +Whether or not the buildpack will be used for staging | +
| locked | +boolean | +Whether or not the buildpack is locked to prevent updating the bits | +
| metadata.labels | +label object | +Labels applied to the buildpack | +
| metadata.annotations | +annotation object | +Annotations applied to the buildpack | +
Permitted roles
+ +| + |
|---|
| Admin | +
Delete a buildpack
+Example Request
+curl "https://api.example.org/v3/buildpacks/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/buildpacks/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
Upload buildpack bits
+Example Request
+curl "https://api.example.org/v3/buildpacks/[guid]/upload" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -F bits=@"buildpack.zip"
+Example Response
+HTTP/1.1 202 OK
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/[guid]
+
+ {
+ "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
+ "created_at": "2016-03-18T23:26:46Z",
+ "updated_at": "2016-10-17T20:00:42Z",
+ "name": "ruby_buildpack",
+ "state": "AWAITING_UPLOAD",
+ "filename": null,
+ "stack": "windows64",
+ "position": 42,
+ "enabled": true,
+ "locked": false,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload",
+ "method": "POST"
+ }
+ }
+ }
+
+Upload a zip file containing a Cloud Foundry compatible buildpack. The file must be sent as part of a multi-part form.
+ +Definition
+ +POST /v3/buildpacks/:guid/upload
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| bits | +form field | +A binary zip file containing the buildpack bits | +
Permitted roles
+ +| + |
|---|
| Admin | +
Deployments
+ +Deployments are objects that manage updates to applications with zero downtime.
+ +They can either:
+ +-
+
Manage updating an app’s droplet directly after an application package is staged
+Roll an app back to a specific revision along with its associated droplet
+
Deployments are different than the traditional method of pushing app updates which performs start/stop deployments.
+ +Deployment strategies supported:
+ +-
+
Rolling deployments allows for +applications to be deployed without incurring downtime by gradually rolling out instances. Max-in-flight can be configured +to specify how many instances are rolled out simultaneously.
+Canary deployments deploy a single instance and pause for user evaluation. If the canary instance is deemed successful, the deployment can be resumed via the continue action. The deployment then continues like a rolling deployment. This feature is experimental and is subject to change.
+
The deployment object
+Example Deployment object
+
+{
+ "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
+ "status": {
+ "value": "ACTIVE",
+ "reason": "DEPLOYING",
+ "details": {
+ "last_successful_healthcheck": "2018-04-25T22:42:10Z"
+ }
+ },
+ "strategy": "canary",
+ "options" : {
+ "max_in_flight": 3,
+ },
+ "droplet": {
+ "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
+ },
+ "previous_droplet": {
+ "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
+ },
+ "new_processes": [
+ {
+ "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
+ "type": "web"
+ }
+ ],
+ "revision": {
+ "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
+ "version": 1
+ },
+ "created_at": "2018-04-25T22:42:10Z",
+ "updated_at": "2018-04-25T22:42:10Z",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
+ "method": "POST"
+ }
+ "continue": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue",
+ "method": "POST"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the deployment | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| status.value | +string | +The current status of the deployment; valid values are ACTIVE (meaning in progress) and FINALIZED (meaning finished, either successfully or not) |
+
| status.reason | +string | +The reason for the status of the deployment; following list represents valid values: 1. If status.value is ACTIVE- DEPLOYING- PAUSED (only valid for canary deployments) - CANCELING2. If status.value is FINALIZED- DEPLOYED- CANCELED- SUPERSEDED (another deployment created for app before completion) |
+
| status.details.last_successful_healthcheck | +timestamp | +Timestamp of the last successful healthcheck | +
| status.details.last_status_change | +timestamp | +Timestamp of last change to status.value or status.reason | +
| strategy | +string | +Strategy used for the deployment; supported strategies are rolling and canary (experimental) |
+
| options.max_in_flight | +integer | +The maximum number of new instances to deploy simultaneously | +
| droplet.guid | +string | +The droplet guid that the deployment is transitioning the app to | +
| previous_droplet.guid | +string | +The app’s current droplet guid before the deployment was created | +
| new_processes | +array | +List of processes created as part of the deployment | +
| revision | +object | +The revision the deployment is transitioning the app to | +
| relationships.app | +to-one relationship | +The app the deployment is updating | +
| metadata.labels | +label object | +Labels applied to the deployment | +
| metadata.annotations | +annotation object | +Annotations applied to the deployment | +
| links | +links object | +Links to related resources | +
Create a deployment
+Example Request with Droplet
+curl "https://api.example.org/v3/deployments" \
+-X POST \
+-H "Authorization: bearer [token]" \
+-H "Content-type: application/json" \
+-d '{
+ "droplet": {
+ "guid": "[droplet-guid]"
+ },
+ "strategy": "rolling",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "[app-guid]"
+ }
+ }
+ }
+}'
+Example Request with Revision
+curl "https://api.example.org/v3/deployments" \
+-X POST \
+-H "Authorization: bearer [token]" \
+-H "Content-type: application/json" \
+-d '{
+ "revision": {
+ "guid": "[revision-guid]"
+ },
+ "strategy": "rolling",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "[app-guid]"
+ }
+ }
+ }
+}'
+Example Response
+HTTP/1.1 201 OK
+Content-Type: application/json
+
+
+{
+ "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
+ "status": {
+ "value": "ACTIVE",
+ "reason": "DEPLOYING",
+ "details": {
+ "last_successful_healthcheck": "2018-04-25T22:42:10Z"
+ }
+ },
+ "strategy": "canary",
+ "options" : {
+ "max_in_flight": 3,
+ },
+ "droplet": {
+ "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
+ },
+ "previous_droplet": {
+ "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
+ },
+ "new_processes": [
+ {
+ "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
+ "type": "web"
+ }
+ ],
+ "revision": {
+ "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
+ "version": 1
+ },
+ "created_at": "2018-04-25T22:42:10Z",
+ "updated_at": "2018-04-25T22:42:10Z",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
+ "method": "POST"
+ }
+ "continue": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue",
+ "method": "POST"
+ }
+ }
+}
+
+When you create a new deployment you can either provide a specific droplet or revision to deploy. If no revision or droplet is provided, the droplet associated with the app is deployed.
+ +Definition
+ +POST /v3/deployments
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| relationships.app | +to-one relationship | +The app to deploy a droplet for | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| droplet[1] | +object | +The droplet to deploy for the app; this will update the app’s current droplet to this droplet | +The app’s current droplet | +
| revision[1] | +object | +The revision whose droplet to deploy for the app; this will update the app’s current droplet to this droplet | ++ |
| strategy | +string | +The strategy to use for the deployment | +rolling |
+
| options.max_in_flight | +integer | +The maximum number of new instances to deploy simultaneously | +1 | +
| metadata.labels | +label object | +Labels applied to the deployment | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the deployment | ++ |
1 Only a droplet or a revision may be provided, not both.
+ +Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Get a deployment
+Example Request
+curl "https://api.example.org/v3/deployments/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+
+{
+ "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
+ "status": {
+ "value": "ACTIVE",
+ "reason": "DEPLOYING",
+ "details": {
+ "last_successful_healthcheck": "2018-04-25T22:42:10Z"
+ }
+ },
+ "strategy": "canary",
+ "options" : {
+ "max_in_flight": 3,
+ },
+ "droplet": {
+ "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
+ },
+ "previous_droplet": {
+ "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
+ },
+ "new_processes": [
+ {
+ "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
+ "type": "web"
+ }
+ ],
+ "revision": {
+ "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
+ "version": 1
+ },
+ "created_at": "2018-04-25T22:42:10Z",
+ "updated_at": "2018-04-25T22:42:10Z",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
+ "method": "POST"
+ }
+ "continue": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue",
+ "method": "POST"
+ }
+ }
+}
+
+Definition
+ +GET /v3/deployments/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List deployments
+Example Request
+curl "https://api.example.org/v3/deployments" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/deployments?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/deployments?page=1&per_page=2"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
+ "status": {
+ "value": "FINALIZED",
+ "reason": "DEPLOYED"
+ },
+ "strategy": "rolling",
+ "options" : {
+ "max_in_flight": 1,
+ },
+ "droplet": {
+ "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
+ },
+ "previous_droplet": {
+ "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
+ },
+ "new_processes": [
+ {
+ "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
+ "type": "web-deployment-59c3d133-2b83-46f3-960e-7765a129aea4"
+ }
+ ],
+ "revision": {
+ "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
+ "version": 1
+ },
+ "created_at": "2018-04-25T22:42:10Z",
+ "updated_at": "2018-04-25T22:42:10Z",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all deployments the user has access to.
+ +Definition
+ +GET /v3/deployments
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| states | +list of strings | +Comma-delimited list of states to filter by | +
| status_reasons | +list of strings | +Comma-delimited list of status reasons to filter by; valid values include DEPLOYING, PAUSED, CANCELING, DEPLOYED, CANCELED, SUPERSEDED |
+
| status_values | +list of strings | +Comma-delimited list of status values to filter by; valid values include ACTIVE and FINALIZED |
+
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Update a deployment
+Example Request
+curl "https://api.example.org/v3/deployments/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+
+{
+ "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
+ "status": {
+ "value": "ACTIVE",
+ "reason": "DEPLOYING",
+ "details": {
+ "last_successful_healthcheck": "2018-04-25T22:42:10Z"
+ }
+ },
+ "strategy": "canary",
+ "options" : {
+ "max_in_flight": 3,
+ },
+ "droplet": {
+ "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
+ },
+ "previous_droplet": {
+ "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
+ },
+ "new_processes": [
+ {
+ "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
+ "type": "web"
+ }
+ ],
+ "revision": {
+ "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
+ "version": 1
+ },
+ "created_at": "2018-04-25T22:42:10Z",
+ "updated_at": "2018-04-25T22:42:10Z",
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel",
+ "method": "POST"
+ }
+ "continue": {
+ "href": "https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue",
+ "method": "POST"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/deployments/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the deployment | +
| metadata.annotations | +annotation object | +Annotations applied to the deployment | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Cancel a deployment
+Example Request
+curl "https://api.example.org/v3/deployments/[guid]/actions/cancel" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+
+Definition
+ +POST /v3/deployments/:guid/actions/cancel
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Continue a deployment
+Example Request
+curl "https://api.example.org/v3/deployments/[guid]/actions/continue" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+
+Definition
+ +POST /v3/deployments/:guid/actions/continue
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Domains
+ +Domains represent a fully qualified domain name that is used for application routes.
+ +A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.
+The domain object
+Example Domain object
+{
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "name": "test-domain.com",
+ "internal": false,
+ "router_group": null,
+ "supported_protocols": ["http"],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "organization": {
+ "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
+ },
+ "shared_organizations": {
+ "data": [
+ {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
+ {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
+ },
+ "route_reservations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
+ },
+ "shared_organizations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the domain | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +The name of the domain; must be between 3 ~ 253 characters and follow RFC 1035 |
+
| internal | +boolean | +Whether the domain is used for internal (container-to-container) traffic | +
| router_group.guid | +uuid | +The guid of the desired router group to route tcp traffic through; if set, the domain will only be available for tcp traffic |
+
| supported_protocols | +list of strings | +Available protocols for routes using the domain, currently http and tcp |
+
| relationships.organization | +to-one relationship | +The organization the domain is scoped to; if set, the domain will only be available in that organization; otherwise, the domain will be globally available | +
| relationships.shared_organizations | +to-many relationship | +Organizations the domain is shared with; if set, the domain will be available in these organizations in addition to the organization the domain is scoped to | +
| metadata.labels | +label object | +Labels applied to the domain | +
| metadata.annotations | +annotation object | +Annotations applied to the domain | +
| links | +links object | +Links to related resources | +
Create a domain
+Example Request
+curl "https://api.example.org/v3/domains" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "example.com",
+ "internal": false
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "name": "test-domain.com",
+ "internal": false,
+ "router_group": null,
+ "supported_protocols": ["http"],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "organization": {
+ "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
+ },
+ "shared_organizations": {
+ "data": [
+ {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
+ {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
+ },
+ "route_reservations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
+ },
+ "shared_organizations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
+ }
+ }
+}
+
+Definition
+ +POST /v3/domains
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the domain | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| internal | +boolean | +Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic | +false | +
| router_group.guid | +uuid | +The desired router group guid. note: creates a tcp domain; cannot be used when internal is set to true or domain is scoped to an org |
+null | +
| organization | +to-one relationship | +A relationship to the organization the domain will be scoped to; note: cannot be used when internal is set to true or domain is associated with a router group |
++ |
| shared_organizations | +to-many relationship | +A relationship to organizations the domain will be shared with Note: cannot be used without an organization relationship |
++ |
| metadata.labels | +label object | +Labels applied to the domain | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the domain | ++ |
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +When an organization relationship is provided |
+
Get a domain
+Example Request
+curl "https://api.example.org/v3/domains/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "name": "test-domain.com",
+ "internal": false,
+ "router_group": null,
+ "supported_protocols": ["http"],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "organization": {
+ "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
+ },
+ "shared_organizations": {
+ "data": [
+ {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
+ {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
+ },
+ "route_reservations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
+ },
+ "shared_organizations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
+ }
+ }
+}
+
+Definition
+ +GET /v3/domains/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Auditor | ++ |
| Org Billing Manager | +Can only view domains without an organization relationship | +
| Org Manager | ++ |
| Space Auditor | ++ |
| Space Developer | ++ |
| Space Manager | ++ |
| Space Supporter | ++ |
List domains
+Example Request
+curl "https://api.example.org/v3/domains" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/domains?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/domains?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/domains?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "name": "test-domain.com",
+ "internal": false,
+ "router_group": { "guid": "5806148f-cce6-4d86-7fbd-aa269e3f6f3f" },
+ "supported_protocols": ["tcp"],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "organization": {
+ "data": null
+ },
+ "shared_organizations": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ },
+ "route_reservations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
+ },
+ "router_group": {
+ "href": "https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f"
+ }
+ }
+ },
+ ]
+}
+
+Retrieve all domains the user has access to.
+ +Definition
+ +GET /v3/domains
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of guids to filter by | +
| names | +list of strings | +Comma-delimited list of domain names to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of owning organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + | + |
|---|---|
| All Roles | ++ |
List domains for an organization
+Example Request
+curl "https://api.example.org/v3/organizations/[guid]/domains" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/organizations/[guid]/domains?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/organizations/[guid]/domains?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/organizations/[guid]/domains?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "name": "test-domain.com",
+ "internal": false,
+ "router_group": { "guid": "5806148f-cce6-4d86-7fbd-aa269e3f6f3f" },
+ "supported_protocols": ["tcp"],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "organization": {
+ "data": null
+ },
+ "shared_organizations": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ },
+ "route_reservations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
+ },
+ "router_group": {
+ "href": "https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f"
+ }
+ }
+ },
+ ]
+}
+
+Retrieve all domains available in an organization for the current user. This will return unscoped domains +(those without an owning organization), domains that are scoped to the given organization (owned by the given +organization), and domains that have been shared with the organization.
+ +To retrieve the default domain for an organization, use the get default domain endpoint.
+ +Definition
+ +GET /v3/organizations/:guid/domains
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of guids to filter by | +
| names | +list of strings | +Comma-delimited list of domain names to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of owning organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Update a domain
+Example Request
+curl "https://api.example.org/v3/domains/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "metadata": {
+ "labels": {"key": "value"},
+ "annotations": {"note": "detailed information"}
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "name": "test-domain.com",
+ "internal": false,
+ "router_group": null,
+ "supported_protocols": ["http"],
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "relationships": {
+ "organization": {
+ "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
+ },
+ "shared_organizations": {
+ "data": [
+ {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
+ {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
+ },
+ "route_reservations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
+ },
+ "shared_organizations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/domains/:guid
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| metadata.labels | +label object | +Labels applied to the domain | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the domain | ++ |
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +If domain is scoped to organization managed by the org manager | +
Delete a domain
+Example Request
+curl "https://api.example.org/v3/domains/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/domains/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +If domain is scoped to organization managed by the org manager | +
Share a domain
+Example Request
+curl "https://api.example.org/v3/domains/[guid]/relationships/shared_organizations" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": [
+ {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
+ {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
+ ]
+ }'
+Example Response
+HTTP/1.1 200 Created
+Content-Type: application/json
+
+{
+ "data": [
+ {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"}
+ {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
+ ]
+}
+
+This endpoint shares an organization-scoped domain to other organizations specified by a list of organization guids. This will allow any of the other organizations to use the organization-scoped domain.
+ +Definition
+ +POST /v3/domains/:guid/relationships/shared_organizations
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-many relationship | +The organization guids with which to share the domain | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Org Manager | +
Unshare a domain
+Example Request
+curl "https://api.example.org/v3/domains/[guid]/relationships/shared_organizations/[org_guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json"
+Example Response
+HTTP/1.1 204 No Content
+This endpoint removes an organization from the list of organizations an organization-scoped domain is shared with. This prevents the organization from using the organization-scoped domain.
+ +Definition
+ +DELETE /v3/domains/:guid/relationships/shared_organizations/:org_guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +Can be in either the domain’s owning organization or the organization it has been shared to | +
Droplets
+ +Droplets are the result of staging an application package. There are two types +(lifecycles) of droplets: buildpack and docker. In the case of the buildpacks, +the droplet contains the bits produced by the buildpack, typically application +code and dependencies.
+ +After an application is created and packages are uploaded, a droplet must be +created via a build in order for an application to be deployed or tasks to be run. +The current droplet must be assigned to an +application before it may be started. When tasks are created, +they either use a specific droplet guid, or use the current droplet assigned to an application.
+The droplet object
+Example Droplet object
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "execution_metadata": "",
+ "process_types": {
+ "rake": "bundle exec rake",
+ "web": "bundle exec rackup config.ru -p $PORT"
+ },
+ "checksum": {
+ "type": "sha256",
+ "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "buildpacks": [
+ {
+ "name": "ruby_buildpack",
+ "detect_output": "ruby 1.6.14",
+ "version": "1.1.1.",
+ "buildpack_name": "ruby"
+ }
+ ],
+ "stack": "cflinuxfs4",
+ "image": null,
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the droplet | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| state | +string | +State of the droplet; valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, STAGED, COPYING, FAILED, or EXPIRED |
+
| error | +string | +A string describing the last error during the droplet lifecycle | +
| lifecycle | +lifecycle object | +An object describing the lifecycle that was used when staging the droplet; lifecycle.data will always be an empty hash for lifecycles of type docker |
+
| execution_metadata | +string | +Serialized JSON data resulting from staging for use when executing a droplet | +
| process_types | +object | +The process types (keys) and associated start commands (values) that will be created when the droplet is executed | +
| relationships.app | +to-one relationship | +The app the droplet belongs to | +
| metadata.labels | +labels object | +Labels on the droplet | +
| metadata.annotations | +annotations object | +Annotations on the droplet | +
| links | +links object | +Links to related resources | +
In addition to these fields, a droplet object will contain the following fields from both lifecycles.
+Their values will be null by default and will contain values when the droplet is of a specific lifecycle.type.
Buildpack droplet
+ +| Name | +Type | +Description | +
|---|---|---|
| checksum.type | +string | +Hashing algorithm for checksum; supported algorithms are sha256 and sha1 |
+
| checksum.value | +string | +Checksum of droplet | +
| buildpacks | +array of detected buildpack objects | +Detected buildpacks from the staging process | +
| stack | +string | +The root filesystem to use with the buildpack, for example cflinuxfs4 |
+
Detected buildpack object
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +System buildpack name | +
| detect_output | +string | +Output during buildpack detect process | +
| buildpack_name | +string | +Name reported by the buildpack | +
| version | +string | +Version reported by the buildpack | +
Docker droplet
+ +| Name | +Type | +Description | +
|---|---|---|
| image | +string | +Docker image name | +
Create a droplet
+Example Request
+curl "https://api.example.org/v3/droplets" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "[app-guid]"
+ }
+ }
+ },
+ "process_types": {
+ "rake": "bundle exec rake",
+ "web": "bundle exec rackup config.ru -p $PORT"
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "AWAITING_UPLOAD",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "execution_metadata": "",
+ "process_types": {
+ "rake": "bundle exec rake",
+ "web": "bundle exec rackup config.ru -p $PORT"
+ },
+ "checksum": {
+ "type": "sha256",
+ "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "buildpacks": [
+ {
+ "name": "ruby_buildpack",
+ "detect_output": "ruby 1.6.14",
+ "version": "1.1.1.",
+ "buildpack_name": "ruby"
+ }
+ ],
+ "stack": "cflinuxfs4",
+ "image": null,
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/upload",
+ "method": "POST"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+This endpoint is only for creating a droplet without a package. To create a droplet based on a package, see Create a build.
+ +Definition
+ +POST /v3/droplets
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| app | +to-one relationship | +App to create droplet for | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| process_types | +hash | +Process names and start commands for the droplet | +{"web": ""} |
+
Permitted roles
+ +| + | + |
|---|---|
| Admin | ++ |
| Space Developer | ++ |
Get a droplet
+Example Request
+curl "https://api.example.org/v3/droplets/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "execution_metadata": "",
+ "process_types": {
+ "rake": "bundle exec rake",
+ "web": "bundle exec rackup config.ru -p $PORT"
+ },
+ "checksum": {
+ "type": "sha256",
+ "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "buildpacks": [
+ {
+ "name": "ruby_buildpack",
+ "detect_output": "ruby 1.6.14",
+ "version": "1.1.1.",
+ "buildpack_name": "ruby"
+ }
+ ],
+ "stack": "cflinuxfs4",
+ "image": null,
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +GET /v3/droplets/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | +Some fields are redacted | +
| Org Manager | +Some fields are redacted | +
| Space Auditor | +Some fields are redacted | +
| Space Developer | ++ |
| Space Manager | +Some fields are redacted | +
| Space Supporter | +Some fields are redacted | +
List droplets
+Example Request
+curl "https://api.example.org/v3/droplets" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/droplets?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/droplets?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "image": null,
+ "execution_metadata": "PRIVATE DATA HIDDEN",
+ "process_types": {
+ "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
+ },
+ "checksum": {
+ "type": "sha256",
+ "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "buildpacks": [
+ {
+ "name": "ruby_buildpack",
+ "detect_output": "ruby 1.6.14",
+ "version": "1.1.1.",
+ "buildpack_name": "ruby"
+ }
+ ],
+ "stack": "cflinuxfs4",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "docker",
+ "data": {}
+ },
+ "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
+ "process_types": {
+ "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
+ },
+ "image": "cloudfoundry/diego-docker-app-custom:latest",
+ "checksum": null,
+ "buildpacks": null,
+ "stack": null,
+ "created_at": "2016-03-17T00:00:01Z",
+ "updated_at": "2016-03-17T21:41:32Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+}
+
+Retrieve all droplets the user has access to.
+ +Definition
+ +GET /v3/droplets
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of droplet guids to filter by | +
| states | +list of strings | +Comma-delimited list of droplet states to filter by | +
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at and updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List droplets for a package
+Example Request
+curl "https://api.example.org/v3/packages/[guid]/droplets" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "image": null,
+ "execution_metadata": "PRIVATE DATA HIDDEN",
+ "process_types": {
+ "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
+ },
+ "checksum": {
+ "type": "sha256",
+ "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "buildpacks": [
+ {
+ "name": "ruby_buildpack",
+ "detect_output": "ruby 1.6.14",
+ "version": "1.1.1.",
+ "buildpack_name": "ruby"
+ }
+ ],
+ "stack": "cflinuxfs4",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "docker",
+ "data": {}
+ },
+ "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
+ "process_types": {
+ "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
+ },
+ "image": "cloudfoundry/diego-docker-app-custom:latest",
+ "checksum": null,
+ "buildpacks": null,
+ "stack": null,
+ "created_at": "2016-03-17T00:00:01Z",
+ "updated_at": "2016-03-17T21:41:32Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+}
+
+Retrieve a list of droplets belonging to a package.
+ +Definition
+ +GET /v3/packages/:guid/droplets
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of droplet guids to filter by | +
| states | +list of strings | +Comma-delimited list of droplet states to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at and updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List droplets for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/droplets" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "image": null,
+ "execution_metadata": "PRIVATE DATA HIDDEN",
+ "process_types": {
+ "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
+ },
+ "checksum": {
+ "type": "sha256",
+ "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "buildpacks": [
+ {
+ "name": "ruby_buildpack",
+ "detect_output": "ruby 1.6.14",
+ "version": "1.1.1.",
+ "buildpack_name": "ruby"
+ }
+ ],
+ "stack": "cflinuxfs4",
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "docker",
+ "data": {}
+ },
+ "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
+ "process_types": {
+ "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
+ },
+ "image": "cloudfoundry/diego-docker-app-custom:latest",
+ "checksum": null,
+ "buildpacks": null,
+ "stack": null,
+ "created_at": "2016-03-17T00:00:01Z",
+ "updated_at": "2016-03-17T21:41:32Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+}
+
+Retrieve a list of droplets belonging to an app.
+ +Definition
+ +GET /v3/apps/:guid/droplets
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of droplet guids to filter by | +
| states | +list of strings | +Comma-delimited list of droplet states to filter by | +
| current | +boolean | +If true, only include the droplet currently assigned to the app | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at and updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update a droplet
+Example Request
+curl "https://api.example.space/v3/droplets/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "STAGED",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "execution_metadata": "",
+ "process_types": {
+ "rake": "bundle exec rake",
+ "web": "bundle exec rackup config.ru -p $PORT"
+ },
+ "checksum": {
+ "type": "sha256",
+ "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "buildpacks": [
+ {
+ "name": "ruby_buildpack",
+ "detect_output": "ruby 1.6.14",
+ "version": "1.1.1.",
+ "buildpack_name": "ruby"
+ }
+ ],
+ "stack": "cflinuxfs4",
+ "image": null,
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-03-28T23:39:47Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download"
+ }
+ },
+ "metadata": {
+ "labels": {
+ "release": "stable"
+ },
+ "annotations": {
+ "note": "detailed information"
+ }
+ }
+ }
+
+Definition
+ +PATCH /v3/droplets/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the droplet | +
| metadata.annotations | +annotation object | +Annotations applied to the droplet | +
| image | +string | +Image reference where the built complete image was stored (field can only be passed by Build State Updaters) | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | ++ |
| Build State Updater | +This is a special component role; read more about component roles | +
Delete a droplet
+Example Request
+curl "https://api.example.org/v3/droplets/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/droplets/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Copy a droplet
+Example Request
+curl "https://api.example.org/v3/droplets?source_guid=[guid]" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "[app-guid]"
+ }
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
+ "state": "COPYING",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "execution_metadata": "",
+ "process_types": null,
+ "checksum": null,
+ "buildpacks": null,
+ "stack": null,
+ "image": null,
+ "created_at": "2016-03-28T23:39:34Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "package": {
+ "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
+ "method": "PATCH"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Copy a droplet to a different app. The copied droplet excludes the +environment variables listed on the source droplet.
+ +Definition
+ +POST /v3/droplets?source_guid=:guid
Required query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| source_guid | +uuid | +Source guid of the droplet to be copied | +
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| relationships.app | +to-one relationship | +A relationship to the destination app | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Download droplet bits
+Example Request
+curl "https://api.example.org/v3/droplets/[guid]/download" \
+ -X GET \
+ -H "Authorization: bearer [token]" \
+Example Response
+HTTP/1.1 302 FOUND
+Content-Type: application/json
+Download a gzip compressed tarball file containing a Cloud Foundry compatible +droplet. When using a remote blobstore, such as AWS, the response is a redirect +to the actual location of the bits. If the client is automatically following +redirects, then the OAuth token that was used to communicate with Cloud +Controller will be relayed on the new redirect request. Some blobstores may +reject the request in that case. Clients may need to follow the redirect +without including the OAuth token.
+ +Only droplets that are in the STAGED state and have lifecycle type
+buildpack can be downloaded.
Definition
+ +GET /v3/droplets/:guid/download
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
Upload droplet bits
+Example Request
+curl "https://api.example.org/v3/droplets/[guid]/upload" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -F bits=@"droplet.tgz"
+Example Response
+HTTP/1.1 202 OK
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/[guid]
+
+{
+ "guid": "3c64aba2-2d9e-4eea-9e07-6fec1636315e",
+ "state": "PROCESSING_UPLOAD",
+ "error": null,
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {}
+ },
+ "checksum": null,
+ "buildpacks": [],
+ "stack": null,
+ "image": null,
+ "execution_metadata": "",
+ "process_types": {
+ "rake": "bundle exec rake",
+ "web": "bundle exec rackup config.ru -p $PORT"
+ },
+ "created_at": "2019-05-15T22:43:54Z",
+ "updated_at": "2019-05-15T22:53:02Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "a7c7b09d-350d-4816-bf0b-18612fb2eab4"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/droplets/3c64aba2-2d9e-4eea-9e07-6fec1636315e"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4"
+ },
+ "assign_current_droplet": {
+ "href": "https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4/relationships/current_droplet",
+ "method": "PATCH"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Upload a gzip compressed tarball file containing a Cloud Foundry compatible droplet. The file must be sent as part of a multi-part form.
+ +Definition
+ +POST /v3/droplets/:guid/upload
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| bits | +form field | +A gzip compressed tarball file with .tgz extension containing the droplet bits |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Environment Variable Groups
+ +There are two types of environment variable groups: running and staging. They are designed to allow platform operators/admins to manage environment variables across all apps in a foundation.
+ +Variables in a running environment variable group will be injected into all running app containers.
+ +Variables in a staging environment variable group will be injected into the staging container for all apps while they are being staged.
+The environment variable group object
+Example environment variable group object
+{
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "running",
+ "var": {
+ "foo": "bar"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/environment_variable_groups/running"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| updated_at | +string | +The time of last update | +
| name | +string | +The name of the group; can only be running or staging |
+
| var | +object | +Environment variables to inject; keys and values must be strings | +
| links | +links object | +Links to related resources | +
Get an environment variable group
+Example Request
+curl "https://api.example.org/v3/environment_variable_groups/[name]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "running",
+ "var": {
+ "foo": "bar"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/environment_variable_groups/running"
+ }
+ }
+}
+
+Definition
+ +GET /v3/environment_variable_groups/:name
Permitted roles
+ +| + |
|---|
| All Roles | +
Update environment variable group
+Example Request
+curl "https://api.example.org/v3/environment_variable_groups/[name]" \
+ -X PATCH \
+ -H "Content-Type: application/json" \
+ -H "Authorization: bearer [token]" \
+ -d '{
+ "var": {
+ "DEBUG": "false"
+ "USER": null
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "var": {
+ "RAILS_ENV": "production",
+ "DEBUG": "false"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/environment_variable_groups/[name]"
+ }
+ }
+}
+Update the environment variable group.
+The variables given in the request will be merged with the existing environment variable group.
+Any requested variables with a value of null will be removed from the group.
+Environment variable names may not start with VCAP_. PORT is not a valid environment variable.
Definition
+ +PATCH /v3/environment_variable_groups/:name
Permitted roles
+ +| + |
|---|
| Admin | +
Feature Flags
+ +Feature flags are runtime flags that enable or disable functionality on the API.
+The feature flag object
+Example Feature Flag object
+ {
+ "name": "my_feature_flag",
+ "enabled": true,
+ "updated_at": "2016-10-17T20:00:42Z",
+ "custom_error_message": "error message the user sees",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/feature_flags/my_feature_flag"
+ }
+ }
+ }
+
+| Name | +Type | +Description | +
|---|---|---|
| name | +string | +The name of the feature flag | +
| enabled | +boolean | +Whether the feature flag is enabled | +
| updated_at | +timestamp | +The time with zone when the object was last updated; this will be blank for feature flags that have not been configured | +
| custom_error_message | +string | +The error string returned by the API when a client performs an action disabled by the feature flag | +
| links | +links object | +Links to related resources | +
List of feature flags
+ +| + |
|---|
Name: app_bits_uploadDefault: true Description: When enabled, space developers can upload app bits. When disabled, only admin users can upload app bits. |
+
Name: app_scalingDefault: true Description: When enabled, space developers can perform scaling operations (i.e. change memory, disk, log rate, or instances). When disabled, only admins can perform scaling operations. |
+
Name: diego_dockerDefault: false Description: When enabled, Docker applications are supported by Diego. When disabled, Docker applications will stop running. It will still be possible to stop and delete them and update their configurations. |
+
Name: diego_cnb (experimental)Default: false Description: When enabled, the staging process using Cloud Native Buildpacks is supported. |
+
Name: env_var_visibilityDefault: true Description: When enabled, all users can see their environment variables. When disabled, no users can see environment variables. |
+
Name: hide_marketplace_from_unauthenticated_usersDefault: 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_creationDefault: 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_matchingDefault: true Description: When enabled, any user can create resource matches. When disabled, the resource match endpoint always returns an empty array of matches. The package upload endpoint will not cache any uploaded packages for resource matching. |
+
Name: route_creationDefault: true Description: When enabled, a space developer can create routes in a space. When disabled, only admin users can create routes. |
+
Name: route_sharing (experimental)Default: false Description: When enabled, Space Developers can share routes between two spaces (even across orgs!) in which they have the Space Developer role. When disabled, Space Developers cannot share routes between two spaces. |
+
Name: service_instance_creationDefault: 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_sharingDefault: 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_usernameDefault: 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_visibilityDefault: true Description: When enabled, space developers can perform a get on the /v2/apps/:guid/env endpoint, and both space developers and space supporters can perform a get on the /v3/apps/:guid/env and /v3/apps/:guid/environment_variables endpoints. When disabled, neither space developers nor space supporters can access these endpoints. |
+
Name: space_scoped_private_broker_creationDefault: 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_creationDefault: true Description: When enabled, space developers can create tasks. When disabled, only admin users can create tasks. |
+
Name: unset_roles_by_usernameDefault: 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_creationDefault: false Description: When enabled, any user can create an organization via the API. When disabled, only admin users can create organizations via the API. |
+
Get a feature flag
+Example Request
+curl "https://api.example.org/v3/feature_flags/[name]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "name": "my_feature_flag",
+ "enabled": true,
+ "updated_at": "2016-10-17T20:00:42Z",
+ "custom_error_message": "error message the user sees",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/feature_flags/my_feature_flag"
+ }
+ }
+ }
+
+Definition
+ +GET /v3/feature_flags/:name
Permitted roles
+ +| + |
|---|
| All Roles | +
List feature flags
+Example Request
+curl "https://api.example.org/v3/feature_flags" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/feature_flags?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/feature_flags?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/feature_flags?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "name": "my_feature_flag",
+ "enabled": true,
+ "updated_at": "2016-10-17T20:00:42Z",
+ "custom_error_message": "error message the user sees",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/feature_flags/my_feature_flag"
+ }
+ }
+ },
+ {
+ "name": "my_second_feature_flag",
+ "enabled": false,
+ "updated_at": null,
+ "custom_error_message": null,
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/feature_flags/my_second_feature_flag"
+ }
+ }
+ }
+ ]
+ }
+
+Retrieve all feature_flags.
+ +Definition
+ +GET /v3/feature_flags
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to name ascending; prepend with - to sort descending. Valid value is name |
+
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Update a feature flag
+Example Request
+curl "https://api.example.org/v3/feature_flags/[name]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "enabled": true,
+ "custom_error_message": "error message the user sees"
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "name": "my_feature_flag",
+ "enabled": true,
+ "updated_at": "2016-10-17T20:00:42Z",
+ "custom_error_message": "error message the user sees",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/feature_flags/my_feature_flag"
+ }
+ }
+ }
+
+Definition
+ +PATCH /v3/feature_flags/:name
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| enabled | +boolean | +Whether the feature flag is enabled | +
| custom_error_message | +string | +The error string returned by the API when a client performs an action disabled by the feature flag | +
Permitted roles
+ +| + |
|---|
| Admin | +
Info
+ +Info endpoints expose Cloud Controller configuration information.
+Get platform info
+Example Request
+curl "https://api.example.org/v3/info" \
+ -X GET
+Example Response with configured values
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "build": "afa73e3fe",
+ "cli_version": {
+ "minimum": "6.22.0",
+ "recommended": "latest"
+ },
+ "custom": {
+ "arbitrary": "stuff"
+ },
+ "description": "Put your apps here!",
+ "name": "Cloud Foundry",
+ "version": 123,
+ "links": {
+ "self": { "href": "http://api.example.com/v3/info" } ,
+ "support": { "href": "http://support.example.com" }
+ }
+}
+
+Example Response with unconfigured values
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "build": "",
+ "cli_version": {
+ "minimum": "",
+ "recommended": ""
+ },
+ "custom": {},
+ "description": "",
+ "name": "",
+ "version": 0,
+ "links": {
+ "self": { "href": "http://api.example.com/v3/info" } ,
+ "support": { "href": "" }
+ }
+}
+
+Definition
+ +GET /v3/info
Authentication
+ +No authentication required.
+Get platform usage summary
+Example Request
+curl "https://api.example.org/v3/info/usage_summary" \
+ -X GET
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "usage_summary": {
+ "started_instances": 294,
+ "memory_in_mb": 123945
+ },
+ "links": {
+ "self": { "href": "http://api.example.com/v3/info/usage_summary" }
+ }
+}
+
+This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation.
+ +Definition
+ +GET /v3/info/usage_summary
Usage summary object
+ +| Name | +Type | +Description | +
|---|---|---|
| started_instances | +integer | +Total number of process instances in the STARTED state |
+
| memory_in_mb | +integer | +Sum of memory usage of all tasks in the RUNNING state and all process instances in the STARTED state |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
Isolation Segments
+ +Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.
+The isolation segment object
+Example Isolation Segment object
+{
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
+ "name": "an_isolation_segment",
+ "created_at": "2016-10-19T20:25:04Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the isolation segment | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the isolation segment | +
| metadata.labels | +labels object | +Labels on the isolation segment | +
| metadata.annotations | +annotations object | +Annotations on the isolation segment | +
| links | +links object | +Links to related resources | +
Create an isolation segment
+Example Request
+curl "https://api.example.org/v3/isolation_segments" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my_segment"
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
+ "name": "an_isolation_segment",
+ "created_at": "2016-10-19T20:25:04Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+}
+
+Definition
+ +POST /v3/isolation_segments
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness | +
| metadata.labels | +label object | +Labels applied to the isolation segment | +
| metadata.annotations | +annotation object | +Annotations applied to the isolation segment | +
Permitted roles
+ +| + |
|---|
| Admin | +
Get an isolation segment
+Example Request
+curl "https://api.example.org/v3/isolation_segments/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
+ "name": "an_isolation_segment",
+ "created_at": "2016-10-19T20:25:04Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+}
+
+Retrieve an isolation segment to which the user has access. For admin, this is any isolation segment in the system. For anyone else, this is an isolation segment in the allowed list for any organization to which the user belongs.
+ +Definition
+ +GET /v3/isolation_segments/:guid
Permitted roles
+ +| + |
|---|
| All Roles | +
List isolation segments
+Example Request
+curl "https://api.example.org/v3/isolation_segments" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 11,
+ "total_pages": 3,
+ "first": {
+ "href": "https://api.example.org/v3/isolation_segments?page=1&per_page=5"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/isolation_segments?page=3&per_page=5"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/isolation_segments?page=2&per_page=5"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
+ "name": "an_isolation_segment",
+ "created_at": "2016-10-19T20:25:04Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+ },
+ {
+ "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac",
+ "name": "an_isolation_segment1",
+ "created_at": "2016-10-19T20:29:19Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+ },
+ {
+ "guid": "ecdc67c3-a71e-43ff-bddf-048930b8cd03",
+ "name": "an_isolation_segment2",
+ "created_at": "2016-10-19T20:29:22Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+ },
+ {
+ "guid": "424c89e4-4353-46b7-9bf4-f90bd9bacac0",
+ "name": "an_isolation_segment3",
+ "created_at": "2016-10-19T20:29:27Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+ },
+ {
+ "guid": "0a79fcec-a648-4eb8-a6c3-2b5be39047c7",
+ "name": "an_isolation_segment4",
+ "created_at": "2016-10-19T20:29:33Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+ }
+ ]
+}
+
+Retrieves all isolation segments to which the user has access. For admin, this is all the isolation segments in the system. For anyone else, this is the isolation segments in the allowed list for any organization to which the user belongs.
+ +Definition
+ +GET /v3/isolation_segments
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of isolation segment guids to filter by | +
| names | +list of strings | +Comma-delimited list of isolation segment names to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and name |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List organizations relationship
+Example Request
+curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ {
+ "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
+ },
+ {
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
+ },
+ "related": {
+ "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/organizations"
+ }
+ }
+}
+
+This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs.
+ +Definition
+ +GET /v3/isolation_segments/:guid/relationships/organizations
Permitted roles
+ +| + |
|---|
| All Roles | +
List spaces relationship
+Example Request
+curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/spaces" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ {
+ "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
+ }
+ }
+}
+
+This endpoint lists the spaces to which the isolation segment is assigned. For an Admin, this will list all associated spaces in the system. For an org manager, this will list only those associated spaces belonging to orgs for which the user is a manager. For any other user, this will list only those associated spaces to which the user has access.
+ +Definition
+ +GET /v3/isolation_segments/:guid/relationships/spaces
Permitted roles
+ +| + |
|---|
| All Roles | +
Update an isolation segment
+Example Request
+curl "https://api.example.org/v3/isolation_segments/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{ "name": "my_isolation_segment" }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
+ "name": "my_isolation_segment",
+ "created_at": "2016-10-19T20:25:04Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations"
+ }
+ },
+ "metadata": {
+ "annotations": {},
+ "labels": {}
+ }
+}
+
+Definition
+ +PATCH /v3/isolation_segments/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness | +
| metadata.labels | +label object | +Labels applied to the isolation segment | +
| metadata.annotations | +annotation object | +Annotations applied to the isolation segment | +
Permitted roles
+ +| + |
|---|
| Admin | +
Delete an isolation segment
+Example Request
+curl "https://api.example.org/v3/isolation_segments/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+An isolation segment cannot be deleted if it is entitled to any organization.
+ +Definition
+ +DELETE /v3/isolation_segments/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
Entitle organizations for an isolation segment
+Example Request
+curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": [
+ { "guid":"org-guid-1" },
+ { "guid":"org-guid-2" }
+ ]
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ {
+ "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
+ },
+ {
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
+ },
+ "related": {
+ "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/organizations"
+ }
+ }
+}
+
+This endpoint entitles the specified organizations for the isolation segment. +In the case where the specified isolation segment is the system-wide shared segment, and if an organization is not already entitled for any other isolation segment, then the shared isolation segment automatically gets assigned as the default for that organization.
+ +Definition
+ +POST /v3/isolation_segments/:guid/relationships/organizations
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-many relationship | +Organization relationships; each organization will be entitled to manage this isolation segment | +
Permitted roles
+ +| + |
|---|
| Admin | +
Revoke entitlement to isolation segment for an organization
+Example Request
+curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations/[org_guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+This endpoint revokes the entitlement for the specified organization to the isolation segment. If the isolation segment is assigned to a space within an organization, the entitlement cannot be revoked. If the isolation segment is the organization’s default, the entitlement cannot be revoked.
+ +Definition
+ +DELETE /v3/isolation_segments/:guid/relationships/organizations/:org_guid
Permitted roles
+ +| + |
|---|
| Admin | +
Jobs
+ +Jobs are created by the platform when performing certain asynchronous actions.
+The job object
+Example Job object
+{
+ "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
+ "created_at": "2016-10-19T20:25:04Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "operation": "app.delete",
+ "state": "COMPLETE",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
+ }
+ },
+ "errors": [],
+ "warnings": []
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the job | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| operation | +string | +Current desired operation of the job on a model | +
| state | +string | +State of the job; valid values are PROCESSING, POLLING, COMPLETE, orFAILED |
+
| errors | +errors list | +Array of errors that occurred while processing the job | +
| warnings | +warnings list | +Array of warnings that occurred while processing the job | +
| links | +links object | +Links to related resources | +
Note: POLLING happens during asynchronous services operations that require polling the last operation from the service broker.
Get a job
+Example Request
+curl "https://api.example.org/v3/jobs/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Completed Job Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
+ "created_at": "2016-10-19T20:25:04Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "operation": "app.delete",
+ "state": "COMPLETE",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
+ }
+ },
+ "errors": [],
+ "warnings": []
+}
+
+Failed Job Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
+ "created_at": "2016-10-19T20:25:04Z",
+ "updated_at": "2016-11-08T16:41:26Z",
+ "operation": "app.delete",
+ "state": "FAILED",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
+ }
+ },
+ "errors": [
+ {
+ "code": 10008,
+ "title": "CF-UnprocessableEntity",
+ "detail": "something went wrong"
+ }
+ ],
+ "warnings": [
+ {
+ "detail": "warning! warning!"
+ }
+ ]
+}
+
+Definition
+ +GET /v3/jobs/:guid
Permitted roles
+ +| + |
|---|
| All Roles | +
Manifests
+A manifest is a method for applying bulk configurations to apps and their underlying processes.
+ +Manifests are in the YAML format. However, anchors and aliases are not supported.
+ +The manifest schema
+Example Manifest
+---
+version: 1
+applications:
+- name: app1
+ buildpacks:
+ - ruby_buildpack
+ - java_buildpack
+ env:
+ VAR1: value1
+ VAR2: value2
+ routes:
+ - route: route.example.com
+ - route: another-route.example.com
+ protocol: http2
+ services:
+ - my-service1
+ - my-service2
+ - name: my-service-with-arbitrary-params
+ binding_name: my-binding
+ parameters:
+ key1: value1
+ key2: value2
+ stack: cflinuxfs4
+ metadata:
+ annotations:
+ contact: "bob@example.com jane@example.com"
+ labels:
+ sensitive: true
+ processes:
+ - type: web
+ command: start-web.sh
+ disk_quota: 512M
+ health-check-http-endpoint: /healthcheck
+ health-check-type: http
+ health-check-invocation-timeout: 10
+ instances: 3
+ memory: 500M
+ log-rate-limit-per-second: 1KB
+ timeout: 10
+ - type: worker
+ command: start-worker.sh
+ disk_quota: 1G
+ health-check-type: process
+ instances: 2
+ memory: 256M
+ log-rate-limit-per-second: 1KB
+ timeout: 15
+- name: app2
+ env:
+ VAR1: value1
+ processes:
+ - type: web
+ instances: 1
+ memory: 256M
+ log-rate-limit-per-second: 1KB
+ sidecars:
+ - name: authenticator
+ process_types: [ 'web', 'worker' ]
+ command: bundle exec run-authenticator
+ memory: 800M
+
+ - name: upcaser
+ process_types: [ 'worker' ]
+ command: ./tr-server
+ memory: 2G
+Space-level configuration
+ +| Name | +Type | +Description | +
|---|---|---|
| applications | +array of app configurations | +Configurations for apps in the space | +
| version | +integer | +The manifest schema version; currently the only valid version is 1, defaults to 1 if not provided |
+
App-level configuration
+ +This configuration is specified per application and applies to all of the application’s processes.
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the app | +
| lifecycle | +string | +Type of the lifecycle; valid values are buildpack, cnb, docker. Defaults to buildpack, unless the docker property is present. |
+
| buildpacks | +list of strings | +a) An empty array, which will automatically select the appropriate default buildpack according to the coding language (incompatible with lifecycle: cnb) b) An array of one or more URLs pointing to buildpacks c) An array of one or more installed buildpack names Replaces the legacy buildpack field |
+
| docker | +object | +If present, the created app will have Docker lifecycle type; the value of this key is ignored by the API but may be used by clients to source the registry address of the image and credentials, if needed; the generate manifest endpoint will return the registry address of the image and username provided with this key | +
| env | +object | +A key-value mapping of environment variables to be used for the app when running | +
| no-route | +boolean | +When set to true, any routes specified with the routes attribute will be ignored and any existing routes will be removed |
+
| processes | +array of process configurations | +List of configurations for individual process types | +
| random-route | +boolean | +Creates a random route for the app if true; if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored regardless of its value |
+
| default-route | +boolean | +If true, a route for the app will be created using the app name as the hostname and the containing organization’s default domain as the domain; if routes is specified, if the app already has routes, or if no-route is specified, this field is ignored regardless of its value |
+
| routes | +array of route configurations | +List declaring HTTP and TCP routes to be mapped to the app. | +
| services | +array of service configurations | +A list of service-instances to bind to the app | +
| sidecars | +array of sidecar configurations | +A list of configurations for individual sidecars | +
| stack | +string | +The root filesystem to use with the buildpack, for example cflinuxfs4 |
+
| metadata.labels | +label object | +Labels applied to the app | +
| metadata.annotations | +annotation object | +Annotations applied to the app | +
| buildpack | +string | +DEPRECATED in favor of the buildpacks field above |
+
Process-level configuration
+ +This configuration is for the individual process. Each process is created if it does not already exist.
+ +For backwards compatibility, the web process configuration may be placed at the top level of the application configuration, rather than listed under processes. However, if there is a process with type: web listed under processes, this configuration will override any at the top level.
| Name | +Type | +Description | +
|---|---|---|
| type | +string | +(Required) The identifier for the processes to be configured | +
| command | +string | +The command used to start the process; this overrides start commands from Procfiles and buildpacks | +
| disk_quota | +string | +The disk limit for all instances of the web process; this attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case |
+
| health-check-http-endpoint | +string | +Endpoint called to determine if the app is healthy | +
| health-check-invocation-timeout | +integer | +The timeout in seconds for individual health check requests for http and port health checks | +
| health-check-type | +string | +Type of health check to perform; none is deprecated and an alias to process |
+
| instances | +integer | +The number of instances to run | +
| memory | +string | +The memory limit for all instances of the web process; this attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case |
+
| log-rate-limit-per-second | +string | +The log rate limit for all the instances of the process; this attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case, or -1 or 0 |
+
| timeout | +integer | +Time in seconds at which the health-check will report failure | +
Route-level configuration
+ +This configuration is for creating mappings between the app and a route. Each route is created if it does not already exist. The protocol +will be updated for any existing route mapping.
+ +| Name | +Type | +Description | +
|---|---|---|
| route | +string | +(Required) The route URI. Example: host.domain.com |
+
| protocol | +string | +Protocol to use for this route. Valid protocols are http1, http2, and tcp. |
+
Service-level configuration
+ +This configuration is creating new service bindings between the app and a service instance. The services field can
+take either an array of service instance name strings or an array of the following service-level fields.
| Name | +Type | +Description | +
|---|---|---|
| name | +string | +(Required) The name of the service instance to be bound to | +
| binding_name | +string | +The name of the service binding to be created | +
| parameters | +object | +A map of arbitrary key/value pairs to send to the service broker during binding | +
Sidecar-level configuration
+ +This configuration is for the individual sidecar. Each sidecar is created if it does not already exist.
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +(Required) The identifier for the sidecars to be configured | +
| command | +string | +The command used to start the sidecar | +
| process_types | +list of strings | +List of processes to associate sidecar with | +
| memory | +integer | +Memory in MB that the sidecar will be allocated | +
Apply a manifest to a space
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/actions/apply_manifest" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/x-yaml" \
+ --data-binary @/path/to/manifest.yml
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Apply changes specified in a manifest to the named apps and their underlying +processes. The apps must reside in the space. These changes are additive +and will not modify any unspecified properties or remove any existing +environment variables, routes, or services.
+ + + +Definition
+ +POST /v3/spaces/:guid/actions/apply_manifest
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Generate a manifest for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/manifest" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/x-yaml
+
+---
+applications:
+- name: my-app
+ stack: cflinuxfs4
+ services:
+ - my-service
+ routes:
+ - route: my-app.example.com
+ protocol: http1
+ processes:
+ - type: web
+ instances: 2
+ memory: 512M
+ log-rate-limit-per-second: 1KB
+ disk_quota: 1024M
+ health-check-type: http
+ health-check-http-endpoint: /healthy
+ health-check-invocation-timeout: 10
+ health-check-interval: 5
+ readiness-health-check-type: http
+ readiness-health-check-http-endpoint: /ready
+ readiness-health-check-invocation-timeout: 20
+ readiness-health-check-interval: 5
+Generate a manifest for an app and its underlying processes.
+ +Definition
+ +GET /v3/apps/:guid/manifest
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Space Developer | +
Create a manifest diff for a space (experimental)
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/manifest_diff" \
+ -X POST \
+ -H "Content-Type: application/x-yaml" \
+ -H "Authorization: bearer [token]" \
+ --data-binary @/path/to/manifest.yml
+Example Response
+HTTP/1.1 202 OK
+Content-Type: application/json
+
+{
+ "diff": [
+ {
+ "op": "remove",
+ "path": "/applications/0/routes/1",
+ "was": {"route": "route.example.com"}
+ },
+ {
+ "op": "add",
+ "path": "/applications/1/buildpacks/2",
+ "value": "java_buildpack"
+ },
+ {
+ "op": "replace",
+ "path": "/applications/2/processes/1/memory",
+ "was": "256M",
+ "value": "512M"
+ }
+ ]
+}
+This endpoint returns a JSON representation of the difference between the +provided manifest and the current state of a space.
+ +Currently, this endpoint can only diff version 1 manifests.
+ +The diff object
+ +The diff object format is inspired by the JSON Patch +specification.
+ +| Name | +Type | +Description | +
|---|---|---|
| op | +string | +Type of change; valid values are add, remove, replace |
+
| path | +string | +Path to changing manifest field | +
| was | +any | +For remove and replace operations, the previous value; otherwise key is omitted |
+
| value | +any | +For add and replace operations, the new value; otherwise key is omitted |
+
Definition
+ +POST /v3/spaces/:guid/manifest_diff
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Organizations
+ +An org is a development account that an individual or multiple collaborators can own and use. All collaborators access an org with user accounts. Collaborators in an org share a resource quota plan, applications, services availability, and custom domains.
+The organization object
+Example Organization object
+{
+ "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "my-organization",
+ "suspended": false,
+ "relationships": {
+ "quota": {
+ "data": {
+ "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
+ },
+ "default_domain": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the organization | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the organization | +
| suspended | +boolean | +Whether an organization is suspended or not; non-admins will be blocked from creating, updating, or deleting resources in a suspended organization | +
| relationships.quota | +to-one relationship | +The quota applied to the organization | +
| metadata.labels | +label object | +Labels applied to the organization | +
| metadata.annotations | +annotation object | +Annotations added to the organization | +
| links | +links object | +Links to related resources | +
Create an organization
+Example Request
+curl "https://api.example.org/v3/organizations" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "name": "my-organization" }'
+
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "my-organization",
+ "suspended": false,
+ "relationships": {
+ "quota": {
+ "data": {
+ "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
+ },
+ "default_domain": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +POST /v3/organizations
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Organization name | +
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| suspended | +boolean | +Whether an organization is suspended or not | +
| metadata.labels | +label object | +Labels applied to the organization | +
| metadata.annotations | +annotation object | +Annotations applied to the organization | +
Permitted roles
+ +| + |
|---|
| Admin | +
If the user_org_creation feature flag is enabled, any user with the cloud_controller.write scope will be able to create organizations.
Get an organization
+Example Request
+curl "https://api.example.org/v3/organizations/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "my-organization",
+ "suspended": false,
+ "relationships": {
+ "quota": {
+ "data": {
+ "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
+ },
+ "default_domain": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+This endpoint retrieves the specified organization object.
+ +Definition
+ +GET /v3/organizations/:guid
Permitted roles
+ +| + |
|---|
| All Roles | +
List organizations
+Example Request
+curl "https://api.example.org/v3/organizations" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/organizations?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/organizations?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "org1",
+ "suspended": false,
+ "relationships": {
+ "quota": {
+ "data": {
+ "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains"
+ },
+ "default_domain": {
+ "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains/default"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
+ "created_at": "2017-02-02T00:14:30Z",
+ "updated_at": "2017-02-02T00:14:30Z",
+ "name": "org2",
+ "suspended": false,
+ "relationships": {
+ "quota": {
+ "data": {
+ "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains"
+ },
+ "default_domain": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains/default"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+}
+
+Retrieve all organizations the user has access to.
+ +Definition
+ +GET /v3/organizations
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of organization names to filter by | +
| guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and name |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List organizations for isolation segment
+Example Request
+curl "https://api.example.org/v3/isolation_segments/[guid]/organizations" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/isolation_segments/933b4c58-120b-499a-b85d-4b6fc9e2903b/organizations?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/isolation_segments/933b4c58-120b-499a-b85d-4b6fc9e2903b/organizations?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "org1",
+ "suspended": false,
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains"
+ },
+ "default_domain": {
+ "href": "https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains/default"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ },
+ "relationships": {
+ "quota": {
+ "data": {
+ "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
+ "created_at": "2017-02-02T00:14:30Z",
+ "updated_at": "2017-02-02T00:14:30Z",
+ "name": "org2",
+ "suspended": false,
+ "relationships": {
+ "quota": {
+ "data": {
+ "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains"
+ },
+ "default_domain": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains/default"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+}
+
+Retrieve the organizations entitled to the isolation segment. Return only the organizations the user has access to.
+ +Definition
+ +GET /v3/isolation_segments/:guid/organizations
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of organization names to filter by | +
| guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and name |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Auditor | +
| Org Billing Manager | +
| Org Manager | +
Update an organization
+Example Request
+curl "https://api.example.org/v3/organizations/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "name": "my-organization" }'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "my-organization",
+ "suspended": false,
+ "relationships": {
+ "quota": {
+ "data": {
+ "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains"
+ },
+ "default_domain": {
+ "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +PATCH /v3/organizations/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Organization name | +
| suspended | +boolean | +Whether an organization is suspended or not | +
| metadata.labels | +label object | +Labels applied to the organization | +
| metadata.annotations | +annotation object | +Annotations applied to the organization | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Org Manager | +
Delete an organization
+ +When an organization is deleted, user roles associated with the organization +will also be deleted.
+Example Request
+curl "https://api.example.org/v3/organizations/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/organizations/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
Assign default isolation segment
+Example Request
+curl "https://api.example.org/v3/organizations/[guid]/relationships/default_isolation_segment" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "data": {
+ "guid": "[iso-seg-guid]"
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": {
+ "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment"
+ },
+ "related": {
+ "href": "https://api.example.org/v3/isolation_segments/9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
+ }
+ }
+}
+
+Set the default isolation segment for a given organization. +Only isolation segments that are entitled to the organization are eligible to be the default isolation segment.
+ + + +Definition
+ +PATCH /v3/organizations/:guid/relationships/default_isolation_segment
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-one relationship | +Isolation segment relationship; apps will run in this isolation segment; set data to null to remove the relationship |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Org Manager | +
Get default isolation segment
+Example Request
+curl "https://api.example.org/v3/organizations/[guid]/relationships/default_isolation_segment" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": {
+ "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment"
+ },
+ "related": {
+ "href": "https://api.example.org/v3/isolation_segments/9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
+ }
+ }
+}
+
+Retrieve the default isolation segment for a given organization.
+ +Definition
+ +GET /v3/organizations/:guid/relationships/default_isolation_segment
Permitted roles
+ +| + |
|---|
| All Roles | +
Get default domain
+Example Request
+curl "https://api.example.org/v3/organizations/[guid]/domains/default" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "name": "test-domain.com",
+ "internal": false,
+ "router_group": null,
+ "supported_protocols": ["http"],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "organization": {
+ "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
+ },
+ "shared_organizations": {
+ "data": [
+ {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
+ {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
+ },
+ "route_reservations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
+ },
+ "shared_organizations": {
+ "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
+ }
+ }
+}
+
+Retrieve the default domain for a given organization.
+ +Definition
+ +GET /v3/organizations/:guid/domains/default
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Auditor | ++ |
| Org Billing Manager | +Can only view domains without an organization relationship | +
| Org Manager | ++ |
| Space Auditor | ++ |
| Space Developer | ++ |
| Space Manager | ++ |
| Space Supporter | ++ |
Get usage summary
+Example Request
+curl "https://api.example.org/v3/organizations/[guid]/usage_summary" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "usage_summary": {
+ "started_instances": 3,
+ "memory_in_mb": 50,
+ "routes": 4,
+ "service_instances": 2,
+ "reserved_ports": 1,
+ "domains": 4,
+ "per_app_tasks": 2,
+ "service_keys": 1
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/usage_summary"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
+ }
+ }
+}
+
+This endpoint retrieves the specified organization object’s memory and app instance usage summary.
+ +Definition
+ +GET /v3/organizations/:guid/usage_summary
Permitted roles
+ +| + |
|---|
| All Roles | +
List users for an organization
+Example Request
+curl "https://api.example.org/v3/organizations/:guid/users" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/organizations/:guid/users?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/organizations/:guid/users?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/organizations/:guid/users?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "client_id",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": null,
+ "presentation_name": "client_id",
+ "origin": null,
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ }
+ }
+ },
+ {
+ "guid": "9da93b89-3f89-4f05-7238-8a2b123c79l9",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": "some-name",
+ "presentation_name": "some-name",
+ "origin": "uaa",
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9"
+ }
+ }
+ }
+ ]
+}
+
+
+Retrieve all users with a role in the specified organization.
+ +Definition
+ +GET /v3/organizations/:guid/users
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of user guids to filter by | +
| usernames | +list of strings | +Comma-delimited list of usernames to filter by. Mutually exclusive with partial_usernames | +
| partial_usernames | +list of strings | +Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with usernames | +
| origins | +list of strings | +Comma-delimited list of user origins (user stores) to filter by, for example, users authenticated by UAA have the origin “uaa”; users authenticated by an LDAP provider have the origin “ldap”; when filtering by origins, usernames must be included | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at and updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Organization Quotas
+ +Organization quotas are named sets of memory, log rate, service, and instance usage quotas. For example, one organization quota might allow up to 10 services, 10 routes, and 2 GB of RAM, while another might offer 100 services, 100 routes, and 10 GB of RAM.
+ +An organization has exactly one organization quota. If not specifically assigned a quota, it will have the default quota.
+ +For more information, see the Cloud Foundry docs.
+The organization quota object
+Example Organization Quota object
+ {
+ "guid": "quota-guid",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": 5
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ },
+ "domains": {
+ "total_domains": 7
+ },
+ "relationships": {
+ "organizations": {
+ "data": [
+ { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
+ ]
+ }
+ },
+ "links": {
+ "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
+ }
+ }
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the organization quota | +
| created_at | +timestamp | +The time with zone when the organization quota was created | +
| updated_at | +timestamp | +The time with zone when the organization quota was last updated | +
| name | +string | +Name of the quota | +
| apps | +object | +Quotas that affect applications and application sub-resources | +
| apps.per_process_memory_in_mb | +integer or null |
+Maximum memory for a single process or task | +
| apps.total_memory_in_mb | +integer or null |
+Total memory allowed for all the started processes and running tasks in an organization | +
| apps.total_instances | +integer or null |
+Total instances of all the started processes allowed in an organization | +
| apps.log_rate_limit_in_bytes_per_second | +integer or null |
+Total log rate limit allowed for all the started processes and running tasks in an organization | +
| apps.per_app_tasks | +integer or null |
+Maximum number of running tasks in an organization | +
| services | +object | +Quotas that affect services | +
| services.paid_services_allowed | +boolean | +Specifies whether instances of paid service plans can be created | +
| services.total_service_instances | +integer or null |
+Total number of service instances allowed in an organization | +
| services.total_service_keys | +integer or null |
+Total number of service keys allowed in an organization | +
| routes | +object | +Quotas that affect routes | +
| routes.total_routes | +integer or null |
+Total number of routes allowed in an organization | +
| routes.total_reserved_ports | +integer or null |
+Total number of ports that are reservable by routes in an organization | +
| domains | +object | +Quotas that affect domains | +
| domains.total_domains | +integer or null |
+Total number of domains that can be scoped to an organization | +
| relationships.organizations | +to-many relationship | +A relationship to the organizations where the quota is applied | +
| links | +links object | +Links to related resources | +
Create an organization quota
+Example Request
+curl "https://api.example.org/v3/organization_quotas" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "production"
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+ {
+ "guid": "quota-guid",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": 5
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ },
+ "domains": {
+ "total_domains": 7
+ },
+ "relationships": {
+ "organizations": {
+ "data": [
+ { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
+ ]
+ }
+ },
+ "links": {
+ "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
+ }
+ }
+
+This endpoint creates a new organization quota, but does not assign it to a specific organization unless an organization GUID is provided in the relationships.organizations parameter.
To create an organization quota you must be an admin.
+ +Definition
+ +POST /v3/organization_quotas
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the quota | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| apps | +object | +Quotas that affect applications and application sub-resources | ++ |
| apps.per_process_memory_in_mb | +integer or null |
+Maximum memory for a single process or task | +null (infinite) | +
| apps.total_memory_in_mb | +integer or null |
+Total memory allowed for all the started processes and running tasks in an organization | +null (infinite) | +
| apps.total_instances | +integer or null |
+Total instances of all the started processes allowed in an organization | +null (infinite) | +
| apps.log_rate_limit_in_bytes_per_second | +integer or null |
+Total log rate limit allowed for all the started processes and running tasks in an organization | +null (infinite) | +
| apps.per_app_tasks | +integer or null |
+Maximum number of running tasks in an organization | +null (infinite) | +
| services | +object | +Quotas that affect services | ++ |
| services.paid_services_allowed | +boolean | +Specifies whether instances of paid service plans can be created | +true | +
| services.total_service_instances | +integer or null |
+Total number of service instances allowed in an organization | +null (infinite) | +
| services.total_service_keys | +integer or null |
+Total number of service keys allowed in an organization | +null (infinite) | +
| routes | +object | +Quotas that affect routes | ++ |
| routes.total_routes | +integer or null |
+Total number of routes allowed in an organization | +null (infinite) | +
| routes.total_reserved_ports | +integer or null |
+Total number of ports that are reservable by routes in an organization | +null (infinite) | +
| domains | +object | +Quotas that affect domains | ++ |
| domains.total_domains | +integer or null |
+Total number of domains that can be scoped to an organization | +null (infinite) | +
| relationships.organizations | +to-many relationship | +A relationship to the organizations where the quota is applied | +[] | +
Permitted roles
+ +| + |
|---|
| Admin | +
Get an organization quota
+Example Request
+curl "https://api.example.org/v3/organization_quotas/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "guid": "quota-guid",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": 5
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ },
+ "domains": {
+ "total_domains": 7
+ },
+ "relationships": {
+ "organizations": {
+ "data": [
+ { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
+ ]
+ }
+ },
+ "links": {
+ "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
+ }
+ }
+
+This endpoint gets an individual organization quota resource.
+ +Definition
+ +GET /v3/organization_quotas/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Manager | +Response will only include guids of managed organizations | +
| Org Auditor | +Response will only include guids of audited organizations | +
| Org Billing Manager | +Response will only include guids of billing-managed organizations | +
| Space Auditor | +Response will only include guids of parent organizations | +
| Space Developer | +Response will only include guids of parent organizations | +
| Space Manager | +Response will only include guids of parent organizations | +
| Space Supporter | +Response will only include guids of parent organizations | +
List organization quotas
+Example Request
+curl "https://api.example.org/v3/organization_quotas" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/organization_quotas?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/organization_quotas?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "quota-1-guid",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": 5
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ },
+ "domains": {
+ "total_domains": 7
+ },
+ "relationships": {
+ "organizations": {
+ "data": [
+ { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
+ ]
+ }
+ },
+ "links": {
+ "self": { "href": "https://api.example.org/v3/organization_quotas/quota-1-guid" }
+ }
+ },
+ {
+ "guid": "quota-2-guid",
+ "created_at": "2017-05-04T17:00:41Z",
+ "updated_at": "2017-05-04T17:00:41Z",
+ "name": "sancho-panza",
+ "apps": {
+ "total_memory_in_mb": 2048,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 5,
+ "per_app_tasks": 2
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ },
+ "domains": {
+ "total_domains": 7
+ },
+ "relationships": {
+ "organizations": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": { "href": "https://api.example.org/v3/organization_quotas/quota-2-guid" }
+ }
+ }
+ ]
+ }
+
+This endpoint lists all organization quota resources.
+ +Definition
+ +GET /v3/organization_quotas
| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of organization quota guids to filter by | +
| names | +list of strings | +Comma-delimited list of organization quota names to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Manager | +Response will only include guids of managed organizations | +
| Org Auditor | +Response will only include guids of audited organizations | +
| Org Billing Manager | +Response will only include guids of billing-managed organizations | +
| Space Auditor | +Response will only include guids of parent organizations | +
| Space Developer | +Response will only include guids of parent organizations | +
| Space Manager | +Response will only include guids of parent organizations | +
| Space Supporter | +Response will only include guids of parent organizations | +
Apply an organization quota to an organization
+Example Request
+curl "https://api.example.org/v3/organization_quotas/:quota_guid/relationships/organizations" \
+-X POST \
+-H "Authorization: bearer [token]" \
+-H "Content-type: application/json" \
+-d '{
+ "data": [{ "guid": "org-guid1" }, { "guid": "org-guid2" }]
+}'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+ {
+ "data": [
+ { "guid": "org-guid1" },
+ { "guid": "org-guid2" },
+ { "guid": "previous-org-guid" }
+ ],
+ "links": {
+ "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid/relationships/organizations" }
+ }
+ }
+
+This endpoint applies an organization quota to one or more organizations.
+ +Only admin users can apply an organization quota to an organization.
+ +Definition
+ +POST /v3/organization_quotas/:quota_guid/relationships/organizations
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-many relationship | +Organization guids that the quota will apply to | +
Permitted roles
+ +| + |
|---|
| Admin | +
Delete an organization quota
+ +Organization quotas cannot be deleted when applied to any organizations.
+Example Request
+curl "https://api.example.org/v3/organizations_quotas/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/organization_quotas/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
Update an organization quota
+Example Request
+curl "https://api.example.org/v3/organization_quotas/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": 5
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20,
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ },
+ "domains": {
+ "total_domains": 7
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "guid": "quota-guid",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": 5
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ },
+ "domains": {
+ "total_domains": 7
+ },
+ "relationships": {
+ "organizations": {
+ "data": [
+ { "guid": "9b370018-c38e-44c9-86d6-155c76801104" }
+ ]
+ }
+ },
+ "links": {
+ "self": { "href": "https://api.example.org/v3/organization_quotas/quota-guid" }
+ }
+ }
+
+This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values.
+ +Definition
+ +PATCH /v3/organization_quotas/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the quota | +
| apps | +object | +Quotas that affect applications and application sub-resources | +
| apps.per_process_memory_in_mb | +integer or null |
+Maximum memory for a single process or task | +
| apps.total_memory_in_mb | +integer or null |
+Total memory of all the started processes and running tasks in an organization | +
| apps.total_instances | +integer or null |
+Total instances of all the started processes in an organization | +
| apps.log_rate_limit_in_bytes_per_second | +integer or null |
+Total log rate limit allowed for all the started processes and running tasks in an organization | +
| apps.per_app_tasks | +integer or null |
+Maximum number of running tasks in an organization | +
| services | +object | +Quotas that affect services | +
| services.paid_services_allowed | +boolean | +If instances of paid service plans can be created | +
| services.total_service_instances | +integer or null |
+Total number of service instances in an organization | +
| services.total_service_keys | +integer or null |
+Total number of service keys in an organization | +
| routes | +object | +Quotas that affect routes | +
| routes.total_routes | +integer or null |
+Total number of routes that an organization can have | +
| routes.total_reserved_ports | +integer or null |
+Total number of ports that all routes in an organization can reserve | +
| domains | +object | +Quotas that affect domains | +
| domains.total_domains | +integer or null |
+Total number of domains that can be scoped to an organization | +
Permitted roles
+ +| + |
|---|
| Admin | +
Packages
+ +A package is an application’s ‘source code’; either raw bits for your application or a pointer to these bits.
+ +In Cloud Foundry, packages are staged to produce an executable Droplet. We currently support raw bits and Docker packages.
+The package object
+Example Package object
+{
+ "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
+ "type": "bits",
+ "data": {
+ "checksum": {
+ "type": "sha256",
+ "value": null
+ },
+ "error": null
+ },
+ "state": "PROCESSING_UPLOAD",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
+ "method": "POST"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
+ "method": "GET"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the package | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| type | +string | +Package type; valid values are bits, docker |
+
| data | +object | +Data for package type (see below) | +
| state | +string | +State of the package; valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, EXPIRED |
+
| relationships.app | +to-one relationship | +The app the package belongs to | +
| metadata.labels | +label object | +Labels applied to the package | +
| metadata.annotations | +annotation object | +Annotations applied to the package | +
| links | +links object | +Links to related resources | +
Bits package data
+ +A bits package is used to upload source code for an app to. The bits package will provide an upload link to which a zip file should be uploaded.
| Name | +Type | +Description | +
|---|---|---|
| data.error | +string | +If an error occurs this field will contain the error message | +
| data.checksum.type | +string | +The checksum type, for example: sha256 |
+
| data.checksum.value | +string | +The checksum value; this will be populated after bits are uploaded | +
Docker package data
+ +A Docker package references a Docker image from a registry.
+ +| Name | +Type | +Description | +
|---|---|---|
| data.image | +string | +The registry address of the image | +
| data.username | +string | +The username for the image’s registry | +
| data.password | +string | +The password for the image’s registry | +
Create a package
+Example Request (buildpack app)
+curl "https://api.example.org/v3/packages" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "bits",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "[guid]"
+ }
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
+ "type": "bits",
+ "data": {
+ "checksum": {
+ "type": "sha256",
+ "value": null
+ },
+ "error": null
+ },
+ "state": "PROCESSING_UPLOAD",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
+ "method": "POST"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
+ "method": "GET"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Example Request (Docker app)
+curl "https://api.example.org/v3/packages" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "docker",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "[guid]"
+ }
+ }
+ },
+ "data": {
+ "image": "registry/image:latest",
+ "username": "username",
+ "password": "password"
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "4cb65058-f04f-458f-aca1-5f4e43de6407",
+ "type": "docker",
+ "data": {
+ "image": "registry/image:latest",
+ "username": "username",
+ "password": "***"
+ },
+ "state": "READY",
+ "created_at": "2015-11-03T00:53:54Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "d8b8148d-5798-44de-821a-64b85b15e968"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/4cb65058-f04f-458f-aca1-5f4e43de6407"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/d8b8148d-5798-44de-821a-64b85b15e968"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +POST /v3/packages
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Type of the package; valid values are bits, docker |
+
| relationships.app | +to-one relationship | +A relationship to an app | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| data | +object | +Data for package type | +{} |
+
Conditional Parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data.image | +string | +Required when type is docker; the registry address of the image |
+
| data.username | +string | +Optional when type is docker and accessing a secured registry |
+
| data.password | +string | +Optional when type is docker and accessing a secured registry |
+
| metadata.labels | +label object | +Labels applied to the package | +
| metadata.annotations | +annotation object | +Annotations applied to the package | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Get a package
+Example Request
+curl "https://api.example.org/v3/packages/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
+ "type": "bits",
+ "data": {
+ "checksum": {
+ "type": "sha256",
+ "value": null
+ },
+ "error": null
+ },
+ "state": "PROCESSING_UPLOAD",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
+ "method": "POST"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
+ "method": "GET"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +GET /v3/packages/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List packages
+Example Request
+curl "https://api.example.org/v3/packages" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "a57fd932-85db-483a-a27e-b00efbb3b0a4",
+ "type": "bits",
+ "data": {
+ "checksum": {
+ "type": "sha256",
+ "value": null
+ },
+ "error": null
+ },
+ "state": "AWAITING_UPLOAD",
+ "created_at": "2015-11-03T00:53:54Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "fa3558ce-1c4d-46fc-9776-54b9c8021745"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/upload",
+ "method": "POST"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/download",
+ "method": "GET"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691",
+ "type": "docker",
+ "data": {
+ "image": "registry/image:latest",
+ "username": "username",
+ "password": "***"
+ },
+ "state": "READY",
+ "created_at": "2015-11-03T00:53:54Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "fa3558ce-1c4d-46fc-9776-54b9c8021745"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+}
+
+Retrieve all packages the user has access to.
+ +Definition
+ +GET /v3/packages
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of package guids to filter by | +
| states | +list of strings | +Comma-delimited list of package states to filter by | +
| types | +list of strings | +Comma-delimited list of package types to filter by | +
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List packages for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/packages" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "752edab0-2147-4f58-9c25-cd72ad8c3561",
+ "type": "bits",
+ "data": {
+ "error": null,
+ "checksum": {
+ "type": "sha256",
+ "value": null
+ }
+ },
+ "state": "READY",
+ "created_at": "2016-03-17T21:41:09Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "f2efe391-2b5b-4836-8518-ad93fa9ebf69"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/upload",
+ "method": "POST"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/download",
+ "method": "GET"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+}
+
+Retrieve packages for an app that the user has access to.
+ +Definition
+ +GET /v3/apps/:guid/packages
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of package guids to filter by | +
| states | +list of strings | +Comma-delimited list of package states to filter by | +
| types | +list of strings | +Comma-delimited list of package types to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update a package
+Example Request
+curl "https://api.example.org/v3/packages/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
+ "type": "bits",
+ "data": {
+ "checksum": {
+ "type": "sha256",
+ "value": null
+ },
+ "error": null
+ },
+ "state": "PROCESSING_UPLOAD",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
+ "method": "POST"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
+ "method": "GET"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +PATCH /v3/packages/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the package | +
| metadata.annotations | +annotation object | +Annotations applied to the package | +
| username | +string | +The username for the image’s registry. Only possible for Docker package. | +
| password | +string | +The password for the image’s registry. Only possible for Docker package. | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Delete a package
+Example Request
+curl "https://api.example.org/v3/packages/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/packages/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Copy a package
+Example Request
+curl "https://api.example.org/v3/packages?source_guid=[guid]" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "[destination-app-guid]"
+ }
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "fec72fc1-e453-4463-a86d-5df426f337a3",
+ "type": "docker",
+ "data": {
+ "image": "http://awesome-sauce.example.org"
+ },
+ "state": "COPYING",
+ "created_at": "2016-03-17T21:41:09Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "36208a68-562d-4f51-94ea-28bd8553a271"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/36208a68-562d-4f51-94ea-28bd8553a271"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+This endpoint copies the bits of a source package to a target package.
+ +Definition
+ +POST /v3/packages?source_guid=:guid
Required query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| source_guid | +uuid | +GUID of the source package to copy from | +
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| relationships.app | +to-one relationship | +A relationship to the destination app | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Download package bits
+Example Request
+curl "https://api.example.org/v3/packages/[guid]/download" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 302 Found
+
+You are being redirected.
+
+This endpoint downloads the bits of an existing package.
+When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits.
+If the client is automatically following redirects, then the OAuth token that was used to communicate
+with Cloud Controller will be replayed on the new redirect request. Some blobstores may reject
+the request in that case. Clients may need to follow the redirect without including the OAuth token.
Definition
+ +GET /v3/packages/:guid/download
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Stage a package
+ +Staging a package is accomplished by creating a build. See Create a build.
+Upload package bits
+Example Request
+curl "https://api.example.org/v3/packages/[guid]/upload" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -F bits=@"package.zip" \
+ -F resources='[{"path":"path/to/content.txt","size_in_bytes":123,"checksum": {"value": "b907173290db6a155949ab4dc9b2d019dea0c901"}},{"path":"path/to/code.jar","size_in_bytes":123,"checksum": {"value": "ff84f89760317996b9dd180ab996b079f418396f"}},{"path":"path/to/code.jar","size_in_bytes":123,"checksum": {"value": "ff84f89760317996b9dd180ab996b079f418396f"},"mode":"644"}]'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
+ "type": "bits",
+ "data": {
+ "checksum": {
+ "type": "sha256",
+ "value": null
+ },
+ "error": null
+ },
+ "state": "PROCESSING_UPLOAD",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
+ },
+ "upload": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
+ "method": "POST"
+ },
+ "download": {
+ "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
+ "method": "GET"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+This upload endpoint takes a multi-part form requests for packages of type bits. The request requires either a .zip file uploaded under the bits field or a list of resource match objects under the resources field. These field may be used together.
The resources field in the request accepts the v2 resources object format.
Definition
+ +POST /v3/packages/:guid/upload
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| bits | +form field | +A binary zip file containing the package bits | ++ |
| resources | +form field | +Fingerprints of the application bits that have previously been pushed to Cloud Foundry, formatted as resource match objects | +[] |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Processes
+ +Processes define the runnable units of an app. An app can have multiple process types, each with differing commands and scale. +Processes for an app are defined by the buildpack used to stage the app and can be customized by including a Procfile in the application source.
+ +Web process type
+ +-
+
- By default, a newly created app will come with one instance of the
webprocess and all other process types are scaled to zero
+ - Scale the
webprocess to zero if it is not required for your app
+ - Unless otherwise specified, all routes will be mapped to the
webprocess by default
+
The process object
+Example Process object
+{
+ "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
+ "type": "web",
+ "command": "rackup",
+ "instances": 5,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "health_check": {
+ "type": "port",
+ "data": {
+ "timeout": null
+ }
+ },
+ "readiness_health_check": {
+ "type": "process",
+ "data": {
+ "invocation_timeout": null
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ },
+ "revision": {
+ "data": {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-03-23T18:48:22Z",
+ "updated_at": "2016-03-23T18:48:42Z",
+ "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
+ },
+ "scale": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
+ "method": "POST"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "stats": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the process | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| version | +uuid | +Random identifier that changes every time the process will be recreated in the runtime. | +
| type | +string | +Process type; a unique identifier for processes belonging to an app | +
| command | +string or null | +The command used to start the process; use null to revert to the buildpack-detected or procfile-provided start command | +
| instances | +integer | +The number of instances to run | +
| memory_in_mb | +integer | +The memory in MB allocated per instance | +
| log_rate_limit_in_bytes_per_second | +integer | +The log rate in bytes per second allocated per instance | +
| disk_in_mb | +integer | +The disk in MB allocated per instance | +
| health_check | +health check object | +The health check to perform on the process | +
| readiness_health_check | +readiness health check object | +The readiness health check to perform on the process | +
| relationships.app | +to-one relationship | +The app the process belongs to | +
| relationships.revision | +to-one relationship | +The app revision the process is currently running | +
| metadata.labels | +label object | +Labels applied to the process | +
| metadata.annotations | +annotation object | +Annotations applied to the process | +
| links | +links object | +Links to related resources | +
The health check object
+Example health check object
+{
+ "type": "port",
+ "data": {
+ "timeout": null
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| type | +string | +The type of health check to perform; valid values are http, port, and process; default is port |
+
| data.timeout | +integer | +The duration in seconds that health checks can fail before the process is restarted | +
| data.invocation_timeout | +integer | +The timeout in seconds for individual health check requests for http and port health checks |
+
| data.interval | +integer | +The interval in seconds between health check requests | +
| data.endpoint | +string | +The endpoint called to determine if the app is healthy; this key is only present for http health checks |
+
The readiness health check object
+Example readiness health check object
+{
+ "type": "http",
+ "data": {
+ "endpoint": "/ready",
+ "invocation_timeout": 2
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| type | +string | +The type of health check to perform; valid values are http, port, and process; default is process |
+
| data.invocation_timeout | +integer | +The timeout in seconds for individual health check requests for http and port health checks |
+
| data.interval | +integer | +The interval in seconds between health check requests | +
| data.endpoint | +string | +The endpoint called to determine if the app is ready; this key is only present for http health checks |
+
The process stats object
+ +The process stats object provides information about the status of an individual instance of a process.
+Example process stats object
+{
+ "type": "web",
+ "index": 0,
+ "state": "RUNNING",
+ "usage": {
+ "time": "2016-03-23T23:17:30.476314154Z",
+ "cpu": 0.00038711029163348665,
+ "cpu_entitlement": 0.01117396940977856,
+ "mem": 19177472,
+ "disk": 69705728,
+ "log_rate": 0
+ },
+ "host": "10.244.16.10",
+ "instance_ports": [
+ {
+ "external": 64546,
+ "internal": 8080,
+ "external_tls_proxy_port": 61002,
+ "internal_tls_proxy_port": 61003
+ }
+ ],
+ "uptime": 9042,
+ "mem_quota": 268435456,
+ "disk_quota": 1073741824,
+ "fds_quota": 16384,
+ "isolation_segment": "example_iso_segment",
+ "details": null
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Process type; a unique identifier for processes belonging to an app | +
| index | +integer | +The zero-based index of running instances | +
| state | +string | +The state of the instance; valid values are RUNNING, CRASHED, STARTING, STOPPING, DOWN |
+
| routable | +boolean | +Whether or not the instance is routable (determined by the readiness check of the app). If app readiness checks and routability are unsupported by Diego, this will return as null. |
+
| usage | +object | +Object containing actual usage data for the instance; the value is {} when usage data is unavailable |
+
| usage.time | +timestamp | +The time when the usage was requested | +
| usage.cpu | +number | +The current cpu usage of the instance | +
| usage.mem | +integer | +The current memory usage of the instance | +
| usage.disk | +integer | +The current disk usage of the instance | +
| usage.log_rate | +integer | +The current logging usage of the instance | +
| host | +string | +The host the instance is running on | +
| instance_internal_ip | +string | +The internal IP address of the instance | +
| instance_ports | +object | +JSON array of port mappings between the network-exposed port used to communicate with the app (external) and port opened to the running process that it can listen on (internal) |
+
| uptime | +integer | +The uptime in seconds for the instance | +
| mem_quota | +integer | +The current maximum memory allocated for the instance; the value is null when memory quota data is unavailable |
+
| disk_quota | +integer | +The current maximum disk allocated for the instance; the value is null when disk quota data is unavailable |
+
| log_rate_limit | +integer | +The current maximum log rate allocated for the instance; the value -1 is unlimited, the value is null when the log_rate_limit is unavailable |
+
| fds_quota | +integer | +The maximum file descriptors the instance is allowed to use | +
| isolation_segment | +string | +The current isolation segment that the instance is running on; the value is null when the instance is not placed on a particular isolation segment |
+
| details | +string | +Information about errors placing the instance; the value is null if there are no placement errors |
+
Get a process
+Example Request
+curl "https://api.example.org/v3/processes/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
+ "type": "web",
+ "command": "rackup",
+ "instances": 5,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "health_check": {
+ "type": "port",
+ "data": {
+ "timeout": null
+ }
+ },
+ "readiness_health_check": {
+ "type": "process",
+ "data": {
+ "invocation_timeout": null
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ },
+ "revision": {
+ "data": {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-03-23T18:48:22Z",
+ "updated_at": "2016-03-23T18:48:42Z",
+ "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
+ },
+ "scale": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
+ "method": "POST"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "stats": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
+ }
+ }
+}
+
+Definition
+ +GET /v3/processes/:guid
+GET /v3/apps/:guid/processes/:type
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | +Some fields are redacted | +
| Org Manager | +Some fields are redacted | +
| Space Auditor | +Some fields are redacted | +
| Space Developer | ++ |
| Space Manager | +Some fields are redacted | +
| Space Supporter | +Some fields are redacted | +
Get stats for a process
+ +Process stats are objects that represent the individual instances of a process.
+Example Request
+curl "https://api.example.org/v3/processes/[guid]/stats" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "resources": [
+ {
+ "type": "web",
+ "index": 0,
+ "state": "RUNNING",
+ "usage": {
+ "time": "2016-03-23T23:17:30.476314154Z",
+ "cpu": 0.00038711029163348665,
+ "cpu_entitlement": 0.01117396940977856,
+ "mem": 19177472,
+ "disk": 69705728,
+ "log_rate": 0
+ },
+ "host": "10.244.16.10",
+ "instance_internal_ip": "10.255.93.167",
+ "instance_ports": [
+ {
+ "external": 64546,
+ "internal": 8080,
+ "external_tls_proxy_port": 61002,
+ "internal_tls_proxy_port": 61003
+ }
+ ],
+ "uptime": 9042,
+ "mem_quota": 268435456,
+ "disk_quota": 1073741824,
+ "fds_quota": 16384,
+ "isolation_segment": "example_iso_segment",
+ "log_rate_limit": null,
+ "details": null
+ },
+ {
+ "type": "web",
+ "index": 1,
+ "state": "STARTING",
+ "usage": {
+ "cpu": 0,
+ "cpu_entitlement": 0,
+ "disk": 0,
+ "log_rate": 0,
+ "mem": 0,
+ "time": "2016-03-23T21:34:04+00:00"
+ },
+ "disk_quota": null,
+ "fds_quota": 16384,
+ "host": "",
+ "instance_internal_ip": "",
+ "instance_ports": null,
+ "isolation_segment": null,
+ "log_rate_limit": null,
+ "mem_quota": null,
+ "uptime": 0,
+ "details": null
+ }
+ ]
+}
+
+Definition
+ +GET /v3/processes/:guid/stats
+GET /v3/apps/:guid/processes/:type/stats
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | +Some fields are redacted | +
| Org Manager | +Some fields are redacted | +
| Space Auditor | +Some fields are redacted | +
| Space Developer | ++ |
| Space Manager | +Some fields are redacted | +
| Space Supporter | +Some fields are redacted | +
List processes
+Example Request
+curl "https://api.example.org/v3/processes" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/processes?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/processes?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/processes?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
+ "type": "web",
+ "command": "[PRIVATE DATA HIDDEN IN LISTS]",
+ "instances": 5,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "health_check": {
+ "type": "port",
+ "data": {
+ "timeout": null,
+ "invocation_timeout": null,
+ "interval": null
+ }
+ },
+ "readiness_health_check": {
+ "type": "process",
+ "data": {
+ "invocation_timeout": null,
+ "interval": null
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ },
+ "revision": {
+ "data": {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-03-23T18:48:22Z",
+ "updated_at": "2016-03-23T18:48:42Z",
+ "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
+ },
+ "scale": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
+ "method": "POST"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "stats": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
+ }
+ }
+ },
+ {
+ "guid": "3fccacd9-4b02-4b96-8d02-8e865865e9eb",
+ "type": "worker",
+ "command": "[PRIVATE DATA HIDDEN IN LISTS]",
+ "instances": 1,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "health_check": {
+ "type": "process",
+ "data": {
+ "invocation_timeout": null,
+ "interval": null
+ }
+ },
+ "readiness_health_check": {
+ "type": "http",
+ "data": {
+ "endpoint": "/ready",
+ "invocation_timeout": 2,
+ "interval": 5
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ },
+ "revision": null
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-03-23T18:48:22Z",
+ "updated_at": "2016-03-23T18:48:42Z",
+ "version": "74e513bb-7b9e-445c-84d5-7fea1394e611",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
+ },
+ "scale": {
+ "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/actions/scale",
+ "method": "POST"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "stats": {
+ "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all processes the user has access to.
+ +Definition
+ +GET /v3/processes
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of process guids to filter by | +
| types | +list of strings | +Comma-delimited list of process types to filter by | +
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List processes for app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/processes" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
+ "type": "web",
+ "command": "[PRIVATE DATA HIDDEN IN LISTS]",
+ "instances": 5,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "health_check": {
+ "type": "port",
+ "data": {
+ "timeout": null,
+ "invocation_timeout": null,
+ "interval": null
+ }
+ },
+ "readiness_health_check": {
+ "type": "process",
+ "data": {
+ "invocation_timeout": null,
+ "interval": null
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ },
+ "revision": {
+ "data": {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-03-23T18:48:22Z",
+ "updated_at": "2016-03-23T18:48:42Z",
+ "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
+ },
+ "scale": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
+ "method": "POST"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "stats": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
+ }
+ }
+ },
+ {
+ "guid": "3fccacd9-4b02-4b96-8d02-8e865865e9eb",
+ "type": "worker",
+ "command": "[PRIVATE DATA HIDDEN IN LISTS]",
+ "instances": 1,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "health_check": {
+ "type": "process",
+ "data": {
+ "invocation_timeout": null,
+ "interval": null
+ }
+ },
+ "readiness_health_check": {
+ "type": "http",
+ "data": {
+ "endpoint": "/ready",
+ "invocation_timeout": 2,
+ "interval": 5
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ },
+ "revision": null
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-03-23T18:48:22Z",
+ "updated_at": "2016-03-23T18:48:42Z",
+ "version": "74e513bb-7b9e-445c-84d5-7fea1394e611",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
+ },
+ "scale": {
+ "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/actions/scale",
+ "method": "POST"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "stats": {
+ "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
+ }
+ }
+ }
+ ]
+}
+
+Retrieves all processes belonging to an app.
+ +Definition
+ +GET /v3/apps/:guid/processes
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of process guids to filter by | +
| types | +list of strings | +Comma-delimited list of process types to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update a process
+Example Request
+curl "https://api.example.org/v3/processes/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "command": "rackup",
+ "metadata": {
+ "labels": {
+ "key": "value"
+ },
+ "annotations": {
+ "note": "detailed information"
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
+ "type": "web",
+ "command": "rackup",
+ "instances": 5,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "health_check": {
+ "type": "port",
+ "data": {
+ "timeout": null
+ }
+ },
+ "readiness_health_check": {
+ "type": "process",
+ "data": {
+ "invocation_timeout": null
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ },
+ "revision": {
+ "data": {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "created_at": "2016-03-23T18:48:22Z",
+ "updated_at": "2016-03-23T18:48:42Z",
+ "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
+ },
+ "scale": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
+ "method": "POST"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "stats": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/processes/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| command | +string or null | +The command used to start the process; use null to revert to the buildpack-detected or procfile-provided start command | +
| health_check | +health check object | +The health check to perform on the process | +
| readiness_health_check | +readiness health check object | +The readiness health check to perform on the process | +
| metadata.labels | +label object | +Labels applied to the process | +
| metadata.annotations | +annotation object | +Annotations applied to the process | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Scale a process
+Example Request
+curl "https://api.example.org/v3/processes/[guid]/actions/scale" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "instances": 5,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024
+ }'
+Example Response
+HTTP/1.1 202 OK
+Content-Type: application/json
+
+{
+ "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
+ "type": "web",
+ "command": "rackup",
+ "instances": 5,
+ "memory_in_mb": 256,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "health_check": {
+ "type": "port",
+ "data": {
+ "timeout": null
+ }
+ },
+ "readiness_health_check": {
+ "type": "process",
+ "data": {
+ "invocation_timeout": null
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ },
+ "revision": {
+ "data": {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-03-23T18:48:22Z",
+ "updated_at": "2016-03-23T18:48:42Z",
+ "version": "e9df685c-0464-4aa7-b5f0-8ed843077c13",
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
+ },
+ "scale": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale",
+ "method": "POST"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "stats": {
+ "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
+ }
+ }
+}
+
+Definition
+ +POST /v3/processes/:guid/actions/scale
+POST /v3/apps/:guid/processes/:type/actions/scale
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| instances | +integer | +The number of instances to run | +
| memory_in_mb | +integer | +The memory in mb allocated per instance | +
| disk_in_mb | +integer | +The disk in mb allocated per instance | +
| log_rate_limit_in_bytes_per_second | +integer | +The log rate in bytes per second allocated per instance | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Terminate a process instance
+Example Request
+curl "https://api.example.org/v3/processes/[guid]/instances/[index]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+Terminate an instance of a specific process. Health management will eventually restart the instance.
+ +This allows a user to stop a single misbehaving instance of a process.
+ +Definition
+ +DELETE /v3/processes/:guid/instances/:index
+DELETE /v3/apps/:guid/processes/:type/instances/:index
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Resource Matches
+ +This endpoint matches given resource SHA-1/file size pairs against the Cloud Controller cache
+and reports the subset that describes already cached files.
+This is usually used to avoid uploading duplicate files
+when pushing an app which has only been partially changed.
+The path and mode fields are not used when matching.
When uploading package bits,
+the response from this endpoint should be used as the resources form field.
+As such, it is useful to include the path and mode fields for each resource
+even though they are not used when determining a resource match.
Cloud Foundry operators may set minimum/maximum file sizes to match against. +If the file size provided is outside this range, +it will not be matched against.
+ +If the resource_matching feature flag is disabled,
+resource matching will always return an empty array.
The resource match object
+Example Resource Match object
+{
+ "resources": [
+ {
+ "checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
+ "size_in_bytes": 1,
+ "path": "path/to/file",
+ "mode": "644"
+ }
+ ]
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| checksum.value | +string | +(Required) SHA-1 hash of file | +
| size_in_bytes | +integer | +(Required) Size of file in bytes | +
| path | +string | +Path to the file, relative to app root | +
| mode | +string | +File mode, i.e. POSIX file permissions; defaults to 0744 | +
Create a resource match
+Example Request
+curl "https://api.example.org/v3/resource_matches" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "resources": [
+ {
+ "checksum": { "value": "002d760bea1be268e27077412e11a320d0f164d3" },
+ "size_in_bytes": 36,
+ "path": "C:\\path\\to\\file",
+ "mode": "645"
+ },
+ {
+ "checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
+ "size_in_bytes": 1,
+ "path": "path/to/file",
+ "mode": "644"
+ }
+ ]
+ }'
+
+Example Response
+HTTP/1.1 201 OK
+Content-Type: application/json
+
+{
+ "resources": [
+ {
+ "checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
+ "size_in_bytes": 1,
+ "path": "path/to/file",
+ "mode": "644"
+ }
+ ]
+}
+
+This endpoint returns a list of cached resources from the input list.
+ +Definition
+ +POST /v3/resource_matches
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| resources | +array of resource_object | +List of resources to check for in the resource cache | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Revisions
+ +Revisions represent code used by an application at a specific time. The most recent revision for a running application represents code and configuration currently running in Cloud Foundry. Revisions are not created for Tasks.
+ +Revision are created when the following is changed:
+ +-
+
A new droplet is deployed for an app
+An app is deployed with new environment variables
+The app is deployed with a new or changed custom start command
+An app rolls back to a prior revision
+
Each time a new revision is created the reason(s) for the revisions creation will be appended to its description field.
+ +By default the cloud foundry API retains at most 100 revisions per app.
+The revision object
+Example Revision object
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "version": 1,
+ "droplet": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "processes": {
+ "web": {
+ "command": "bundle exec rackup"
+ }
+ },
+ "sidecars": [
+ {
+ "name": "auth-sidecar",
+ "command": "bundle exec sidecar",
+ "process_types": ["web"],
+ "memory_in_mb": 300
+ }
+ ],
+ "description": "Initial revision.",
+ "deployable": true,
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the revision | +
| version | +integer | +Human-readable identifier for the revision; starts at 1, increments by 1 for each new revision of the app, and rolls back over to 1 at 9999 | +
| droplet | +object | +The droplet used by a process running the revision | +
| processes | +process snapshot object | +An object representing process types at this revision | +
| sidecars | +array of sidecar snapshot objects ] | +The array of sidecars used by processes running the revision | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| description | +string | +A short description of the reason for revision | +
| deployable | +boolean | +Indicates if the revision’s droplet is staged and the revision can be used to create a deployment | +
| relationships.app | +to-one relationship | +The app the revision is associated with | +
| metadata.labels | +label object | +Labels applied to the revision | +
| metadata.annotations | +annotation object | +Annotations applied to the revision | +
| links | +links object | +Links to related resources | +
The process snapshot object
+Example Process Snapshot object
+{
+ "web": {
+ "command": "bundle exec rackup"
+ },
+ "worker": {
+ "command": "bundle exec work"
+ }
+}
+The process snapshot object is a map of process types to objects. +Each object contains the command that the given process type was running at this revision.
+ +The sidecar snapshot object
+Example Sidecar Snapshot object
+{
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300
+}
+| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Human-readable name for the sidecar | +
| command | +string | +The command used to start the sidecar | +
| process_types | +list of strings | +A list of process types the sidecar applies to | +
| memory_in_mb | +integer | +Reserved memory for sidecar | +
Get a revision
+Example Request
+curl "https://api.example.org/v3/revisions/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "version": 1,
+ "droplet": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "processes": {
+ "web": {
+ "command": "bundle exec rackup"
+ }
+ },
+ "sidecars": [
+ {
+ "name": "auth-sidecar",
+ "command": "bundle exec sidecar",
+ "process_types": ["web"],
+ "memory_in_mb": 300
+ }
+ ],
+ "description": "Initial revision.",
+ "deployable": true,
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
+ }
+ }
+}
+
+Definition
+ +GET /v3/revisions/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Get environment variables for a revision
+Example Request
+curl "https://api.example.org/v3/revisions/[guid]/environment_variables" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "var": {
+ "RAILS_ENV": "production"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/revisions/[guid]/environment_variables"
+ },
+ "revision": {
+ "href": "https://api.example.org/v3/revisions/[guid]"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/[app_guid]"
+ }
+ }
+}
+Retrieve the environment variables that are associated with the revision.
+ +Definition
+ +GET /v3/revisions/:guid/environment_variables
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Space Developer | +
List revisions for an app
+Example Request
+curl "https://api.example.org/v3/apps/:guid/revisions" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "version": 1,
+ "droplet": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "processes": {
+ "web": {
+ "command": "bundle exec rackup"
+ }
+ },
+ "sidecars": [
+ {
+ "name": "auth-sidecar",
+ "command": "bundle exec sidecar",
+ "process_types": ["web"],
+ "memory_in_mb": 300
+ }
+ ],
+ "description": "Initial revision.",
+ "deployable": true,
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve revisions for an app the user has access to.
+ +Definition
+ +GET /v3/apps/:guid/revisions
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| versions | +list of strings | +Comma-delimited list of revision versions to filter by | +
| label_selector | +string | +A query string containing a list of label selector requirements | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List deployed revisions for an app
+Example Request
+curl "https://api.example.org/v3/apps/:guid/revisions/deployed" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "version": 1,
+ "droplet": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "processes": {
+ "web": {
+ "command": "bundle exec rackup"
+ }
+ },
+ "sidecars": [
+ {
+ "name": "auth-sidecar",
+ "command": "bundle exec sidecar",
+ "process_types": ["web"],
+ "memory_in_mb": 300
+ }
+ ],
+ "description": "Initial revision.",
+ "deployable": true,
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve deployed revisions for an app the user has access to. +Deployed revisions are revisions that are linked to started processes in the app.
+ +Definition
+ +GET /v3/apps/:guid/revisions/deployed
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending, prepend with - to sort descending. Valid values are created_at, updated_at |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update a revision
+Example Request
+curl "https://api.example.org/v3/revisions/[revguid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "version": 1,
+ "droplet": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ },
+ "processes": {
+ "web": {
+ "command": "bundle exec rackup"
+ }
+ },
+ "sidecars": [
+ {
+ "name": "auth-sidecar",
+ "command": "bundle exec sidecar",
+ "process_types": ["web"],
+ "memory_in_mb": 300
+ }
+ ],
+ "description": "Initial revision.",
+ "deployable": true,
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/revisions/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the revision | +
| metadata.annotations | +annotation object | +Annotations applied to the revision | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Roles
+ +Roles control access to resources in organizations and spaces. +Roles are assigned to users.
+ +For example, a user with the space_developer role is able to push
+applications to their space. A space_manager user can also add roles to users
+within that space (e.g. making a user a space_auditor). An
+organization_manager has wide-reaching privileges, able to create & delete
+spaces, and assign & unassign roles to users.
The role object
+Example Role object
+{
+ "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
+ "created_at": "2019-10-10T17:19:12Z",
+ "updated_at": "2019-10-10T17:19:12Z",
+ "type": "organization_auditor",
+ "relationships": {
+ "user": {
+ "data": {
+ "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ }
+ },
+ "organization": {
+ "data": {
+ "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ },
+ "space": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
+ },
+ "user": {
+ "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the role | +
| created_at | +timestamp | +The time with zone when the role was created | +
| updated_at | +timestamp | +The time with zone when the role was last updated | +
| type | +string | +Role type; see Valid role types | +
| relationships.user | +to-one relationship | +A relationship to the user; this is the user that has the role | +
| relationships.space | +to-one relationship | +A relationship to the space the role controls access to; when this is an organization role, space.data will be null |
+
| relationships.organization | +to-one relationship | +A relationship to the organization the role controls access to; when this is a space role, organization.data will be null |
+
| links | +links object | +Links to related resources | +
Valid role types
+ +-
+
organization_user
+organization_auditor
+organization_manager
+organization_billing_manager
+space_auditor
+space_developer
+space_manager
+space_supporter+ +-
+
- Users with only the space supporter role are not authorized to use the V2 API +
+
Create a role
+Example Request (by user guid)
+curl "https://api.example.org/v3/roles" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "organization_auditor",
+ "relationships": {
+ "user": {
+ "data": {
+ "guid": "user-guid"
+ }
+ },
+ "organization": {
+ "data": {
+ "guid": "org-guid"
+ }
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
+ "created_at": "2019-10-10T17:19:12Z",
+ "updated_at": "2019-10-10T17:19:12Z",
+ "type": "organization_auditor",
+ "relationships": {
+ "user": {
+ "data": {
+ "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ }
+ },
+ "organization": {
+ "data": {
+ "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ },
+ "space": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
+ },
+ "user": {
+ "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ }
+}
+
+Example Request (by username and origin)
+curl "https://api.example.org/v3/roles" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "organization_auditor",
+ "relationships": {
+ "user": {
+ "data": {
+ "username": "user-name",
+ "origin": "ldap"
+ }
+ },
+ "organization": {
+ "data": {
+ "guid": "org-guid"
+ }
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
+ "created_at": "2019-10-10T17:19:12Z",
+ "updated_at": "2019-10-10T17:19:12Z",
+ "type": "organization_auditor",
+ "relationships": {
+ "user": {
+ "data": {
+ "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ }
+ },
+ "organization": {
+ "data": {
+ "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ },
+ "space": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
+ },
+ "user": {
+ "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ }
+}
+
+This endpoint creates a new role for a user in an organization or space.
+ +To create an organization role you must be an admin or organization manager in the organization associated with the role.
+ +To create a space role you must be an admin, an organization manager in the parent organization of the space associated with the role, or a space manager in the space associated with the role.
+ +For a user to be assigned a space role, the user must already have an organization role in the parent organization.
+ +If the associated user is valid but does not exist in Cloud Controller’s database, a user resource will be created automatically.
+ +Definition
+ +POST /v3/roles
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Role to create; see valid role types | +
| relationships.user | +to-one relationship | +A relationship to a user; the user can be defined by either a guid or, if the set_roles_by_username feature_flag is enabled, a username (with the option of including an origin to disambiguate it) |
+
| relationships.organization | +to-one relationship | +A relationship to an organization; required only when creating an organization role | +
| relationships.space | +to-one relationship | +A relationship to a space; required only when creating a space role | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +Can create roles in managed organizations and spaces within those organizations; can also create roles for users outside of managed organizations when set_roles_by_username feature_flag is enabled; this requires identifying users by username and origin |
+
| Space Manager | +Can create roles in managed spaces for users in their org | +
Get a role
+Example Request
+curl "https://api.example.org/v3/roles/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
+ "created_at": "2019-10-10T17:19:12Z",
+ "updated_at": "2019-10-10T17:19:12Z",
+ "type": "organization_auditor",
+ "relationships": {
+ "user": {
+ "data": {
+ "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ }
+ },
+ "organization": {
+ "data": {
+ "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ },
+ "space": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
+ },
+ "user": {
+ "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ }
+}
+
+This endpoint gets an individual role resource.
+ +Definition
+ +GET /v3/roles/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| include | +list of strings | +Optionally include a list of unique related resources in the response; valid values are user, space, and organization |
+
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Manager | +Can see roles in managed organizations or spaces in those organizations | +
| Org Auditor | +Can only see organization roles in audited organizations | +
| Org Billing Manager | +Can only see organization roles in billing-managed organizations | +
| Space Auditor | +Can see roles in audited spaces or parent organizations | +
| Space Developer | +Can see roles in developed spaces or parent organizations | +
| Space Manager | +Can see roles in managed spaces or parent organizations | +
| Space Supporter | +Can see roles in supported spaces or parent organizations | +
List roles
+Example Request
+curl "https://api.example.org/v3/roles" \
+ -X GET \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json"
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/roles?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/roles?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/roles?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "40557c70-d1bd-4976-a2ab-a85f5e882418",
+ "created_at": "2019-10-10T17:19:12Z",
+ "updated_at": "2019-10-10T17:19:12Z",
+ "type": "organization_auditor",
+ "relationships": {
+ "user": {
+ "data": {
+ "guid": "59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ }
+ },
+ "organization": {
+ "data": {
+ "guid": "05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ },
+ "space": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418"
+ },
+ "user": {
+ "href": "https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ }
+ },
+ {
+ "guid": "12347c70-d1bd-4976-a2ab-a85f5e882418",
+ "created_at": "2047-11-10T17:19:12Z",
+ "updated_at": "2047-11-10T17:19:12Z",
+ "type": "space_auditor",
+ "relationships": {
+ "user": {
+ "data": {
+ "guid": "47eadb5f-fc13-414f-84ba-47a35e239cc8"
+ }
+ },
+ "organization": {
+ "data": null
+ },
+ "space": {
+ "data": {
+ "guid": "47c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/roles/12347c70-d1bd-4976-a2ab-a85f5e882418"
+ },
+ "user": {
+ "href": "https://api.example.org/v3/users/47eadb5f-fc13-414f-84ba-77a35e239cc8"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/47c5da3b-6cbc-421c-87c3-20bb3c41ab7c"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint lists roles that the user has access to.
+ +Definition
+ +GET /v3/roles
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of role guids to filter by | +
| types | +list of strings | +Comma-delimited list of role types to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| user_guids | +list of strings | +Comma-delimited list of user guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| include | +list of strings | +Optionally include a list of unique related resources in the response; valid values are user, space, and organization |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Delete a role
+ +This endpoint deletes an individual role.
+Example Request
+curl "https://api.example.org/v3/roles/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/roles/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +Can delete roles in managed organizations or spaces in those organizations | +
| Space Manager | +Can delete roles in managed spaces | +
Root
+ +These endpoints link to other resources, endpoints, and external services that are relevant to API clients.
+Global API Root
+Example Request
+curl "https://api.example.org"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "links": {
+ "self": {
+ "href": "https://api.example.org"
+ },
+ "cloud_controller_v2": {
+ "href": "https://api.example.org/v2",
+ "meta": {
+ "version": "2.155.0"
+ }
+ },
+ "cloud_controller_v3": {
+ "href": "https://api.example.org/v3",
+ "meta": {
+ "version": "3.90.0"
+ }
+ },
+ "network_policy_v0": {
+ "href": "https://api.example.org/networking/v0/external"
+ },
+ "network_policy_v1": {
+ "href": "https://api.example.org/networking/v1/external"
+ },
+ "login": {
+ "href": "https://login.example.org"
+ },
+ "uaa": {
+ "href": "https://uaa.example.org"
+ },
+ "credhub": null,
+ "routing": {
+ "href": "https://api.example.org/routing"
+ },
+ "logging": {
+ "href": "wss://doppler.example.org:443"
+ },
+ "log_cache": {
+ "href": "https://log-cache.example.org"
+ },
+ "log_stream": {
+ "href": "https://log-stream.example.org"
+ },
+ "app_ssh": {
+ "href": "ssh.example.org:2222",
+ "meta": {
+ "host_key_fingerprint": "Y411oivJwZCUQnXHq83mdM5SKCK4ftyoSXI31RRe4Zs",
+ "oauth_client": "ssh-proxy"
+ }
+ }
+ }
+}
+
+This endpoint returns links to the APIs available on a given Cloud Foundry deployment.
+ +Definition
+ +GET /
Authentication
+ +No authentication required.
+V3 API Root
+Example Request
+curl "https://api.example.org/v3"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3"
+ },
+ "app_usage_events": {
+ "href": "https://api.example.org/v3/app_usage_events"
+ },
+ "apps": {
+ "href": "https://api.example.org/v3/apps"
+ },
+ "audit_events": {
+ "href": "https://api.example.org/v3/audit_events"
+ },
+ "buildpacks": {
+ "href": "https://api.example.org/v3/buildpacks"
+ },
+ "builds": {
+ "href": "https://api.example.org/v3/builds"
+ },
+ "deployments": {
+ "href": "https://api.example.org/v3/deployments"
+ },
+ "domains": {
+ "href": "https://api.example.org/v3/domains"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/droplets"
+ },
+ "environment_variable_groups": {
+ "href": "https://api.example.org/v3/environment_variable_groups"
+ },
+ "feature_flags": {
+ "href": "https://api.example.org/v3/feature_flags"
+ },
+ "info": {
+ "href": "https://api.example.org/v3/info"
+ },
+ "isolation_segments": {
+ "href": "https://api.example.org/v3/isolation_segments"
+ },
+ "organizations": {
+ "href": "https://api.example.org/v3/organizations"
+ },
+ "organization_quotas": {
+ "href": "https://api.example.org/v3/organization_quotas"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/packages"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/processes"
+ },
+ "resource_matches": {
+ "href": "https://api.example.org/v3/resource_matches"
+ },
+ "roles": {
+ "href": "https://api.example.org/v3/roles"
+ },
+ "routes": {
+ "href": "https://api.example.org/v3/routes"
+ },
+ "security_groups": {
+ "href": "https://api.example.org/v3/security_groups"
+ },
+ "service_brokers": {
+ "href": "https://api.example.org/v3/service_brokers"
+ },
+ "service_instances": {
+ "href": "https://api.example.org/v3/service_instances",
+ "experimental": true
+ },
+ "service_offerings": {
+ "href": "https://api.example.org/v3/service_offerings"
+ },
+ "service_plans": {
+ "href": "https://api.example.org/v3/service_plans"
+ },
+ "service_usage_events": {
+ "href": "https://api.example.org/v3/service_usage_events"
+ },
+ "spaces": {
+ "href": "https://api.example.org/v3/spaces"
+ },
+ "space_quotas": {
+ "href": "https://api.example.org/v3/space_quotas"
+ },
+ "stacks": {
+ "href": "https://api.example.org/v3/stacks"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/tasks"
+ },
+ "users": {
+ "href": "https://api.example.org/v3/users"
+ }
+ }
+}
+
+This endpoint returns links to all the resources available on the v3 API.
+ +Definition
+ +GET /v3
Authentication
+ +No authentication required.
+Routes
+ +Routes are addresses that direct matched network traffic to one or more destinations. Each route is based on a domain name with additional matching criteria (host (subdomain), path, etc). Matched traffic will be distributed across all destinations, based on their configuration (round-robin by default).
+The route object
+Example Route object
+{
+ "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
+ "protocol": "tcp",
+ "port": 6666,
+ "created_at": "2019-05-10T17:17:48Z",
+ "updated_at": "2019-05-10T17:17:48Z",
+ "host": "a-hostname",
+ "path": "/some_path",
+ "url": "a-hostname.a-domain.com/some_path",
+ "destinations": [
+ {
+ "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
+ "app": {
+ "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "tcp"
+ },
+ {
+ "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
+ "app": {
+ "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "tcp"
+ }
+ ],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
+ }
+ },
+ "domain": {
+ "data": {
+ "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
+ },
+ "domain": {
+ "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
+ },
+ "destinations": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the route | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| protocol | +string | +The protocol supported by the route, based on the route’s domain configuration. Valid protocols are http and tcp |
+
| host | +string | +The hostname for the route; not compatible with routes specifying the tcp protocol;must be either a wildcard (*) or be under 63 characters long and only contain letters, numbers, dashes (-) or underscores(_) |
+
| path | +string | +The path for the route; not compatible with routes specifying the tcp protocol;must be under 128 characters long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from RFC 2396 |
+
| port | +integer or null |
+The port that the route listens on. Only compatible with routes specifying the tcp protocol |
+
| url | +string | +The URL for the route; URLs of protocol http are a combination of host, domain name, and path; URLs of protocol tcp are a combination of domain name and port |
+
| destinations | +array of destination objects | +List of destinations for the route | +
| relationships.space | +to-one relationship | +A relationship to the space containing the route. Routes can only be mapped to destinations in that space | +
| relationships.domain | +to-one relationship | +A relationship to the domain of the route | +
| metadata.labels | +label object | +Labels applied to the route | +
| metadata.annotations | +annotation object | +Annotations applied to the route | +
| links | +links object | +Links to related resources | +
The destination object
+Example Destination object
+{
+ "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
+ "app": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "http2"
+}
+
+A destination represents the relationship between a route and a resource that can serve traffic (for example, the web process of an application).
When a route has destinations, that route will direct traffic to the processes represented by those destinations.
+ +If a destination is created with a port specified, the route will direct traffic to that port on the process. A destination with port 9000 and process type api means traffic will be directed to the api process running on container port 9000.
Note that when using a custom port, the app process must be listening on the specified port for the mapping to work. Otherwise, visiting the route will result in a 404 error.
+ +If a destination does not specify a port, the default port depends on the app lifecycle type. For buildpack apps, traffic will be directed to port 8080. For Docker apps, the first port specified in the Dockerfile will be used.
+ +| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the destination | +
| app.guid | +uuid | +Unique identifier for the app to route traffic to | +
| app.process.type | +string | +Type of the process belonging to the app to route traffic to | +
| port | +integer | +Port on the destination process to route traffic to | +
| weight (deprecated) | +integer or null |
+Percentage of traffic which will be routed to this destination. DEPRECATED: this feature was only available via the experimental Service Mesh routing plane. It is no longer supported. | +
| protocol | +string or null |
+Protocol to use for this destination. Valid protocols are http1 or http2 if route protocol is http, tcp if route protocol is tcp. A null value will set it either http1 or tcp based on the route protocol; this feature is only available if you turn it on in routing release |
+
Create a route
+Example Request
+curl "https://api.example.org/v3/routes" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "host": "a-hostname",
+ "path": "/some_path",
+ "port": 6666,
+ "relationships": {
+ "domain": {
+ "data": { "guid": "domain-guid" }
+ },
+ "space": {
+ "data": { "guid": "space-guid" }
+ }
+ },
+ "metadata": {
+ "labels": { "key": "value" },
+ "annotations": { "note": "detailed information"}
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
+ "protocol": "tcp",
+ "port": 6666,
+ "created_at": "2019-05-10T17:17:48Z",
+ "updated_at": "2019-05-10T17:17:48Z",
+ "host": "a-hostname",
+ "path": "/some_path",
+ "url": "a-hostname.a-domain.com/some_path",
+ "destinations": [
+ {
+ "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
+ "app": {
+ "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "tcp"
+ },
+ {
+ "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
+ "app": {
+ "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "tcp"
+ }
+ ],
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
+ }
+ },
+ "domain": {
+ "data": {
+ "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
+ },
+ "domain": {
+ "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
+ },
+ "destinations": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ }
+ }
+}
+
+Definition
+ +POST /v3/routes
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| relationships.space | +to-one relationship | +A relationship to the space containing the route; routes can only be mapped to destinations in that space | +
| relationships.domain | +to-one relationship | +A relationship to the domain of the route | +
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| host | +string | +The host component for the route; not compatible with routes specifying the tcp protocol |
+
| path | +string | +The path component for the route; should begin with a / and not compatible with routes specifying the tcp protocol |
+
| port | +integer | +The port the route will listen on; only compatible with routes leveraging a domain that supports the tcp protocol. For tcp domains, a port will be randomly assigned if not specified |
+
| metadata.annotations | +annotation object | +Annotations applied to the route | +
| metadata.labels | +label object | +Labels applied to the route | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Get a route
+Example Request
+curl "https://api.example.org/v3/routes/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
+ "protocol": "tcp",
+ "port": 6666,
+ "created_at": "2019-05-10T17:17:48Z",
+ "updated_at": "2019-05-10T17:17:48Z",
+ "host": "a-hostname",
+ "path": "/some_path",
+ "url": "a-hostname.a-domain.com/some_path",
+ "destinations": [
+ {
+ "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
+ "app": {
+ "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "tcp"
+ },
+ {
+ "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
+ "app": {
+ "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "tcp"
+ }
+ ],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
+ }
+ },
+ "domain": {
+ "data": {
+ "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
+ },
+ "domain": {
+ "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
+ },
+ "destinations": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ }
+ }
+}
+
+Definition
+ +GET /v3/routes/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| include | +string | +Optionally include additional related resources in the response Valid values are domain, space.organization, space |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List routes
+Example Request
+curl "https://api.example.org/v3/routes" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/routes?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/routes?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/routes?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
+ "protocol": "http",
+ "created_at": "2019-05-10T17:17:48Z",
+ "updated_at": "2019-05-10T17:17:48Z",
+ "host": "a-hostname",
+ "path": "/some_path",
+ "url": "a-hostname.a-domain.com/some_path",
+ "destinations": [
+ {
+ "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
+ "app": {
+ "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "http1"
+ },
+ {
+ "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
+ "app": {
+ "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "http1"
+ }
+ ],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
+ }
+ },
+ "domain": {
+ "data": {
+ "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
+ },
+ "domain": {
+ "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
+ },
+ "destinations": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all routes the user has access to.
+ +Definition
+ +GET /v3/routes
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| domain_guids | +list of strings | +Comma-delimited list of domain guids to filter by | +
| hosts | +list of strings | +Comma-delimited list of hostnames to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| paths | +list of strings | +Comma-delimited list of paths to filter by (e.g. /path1,/path2) |
+
| ports | +list of integers | +Comma-delimited list of ports to filter by (e.g. 3306,5432) |
+
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| service_instance_guids | +list of strings | +Comma-delimited list of service instance guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| include | +string | +Optionally include a list of unique related resources in the response Valid values are domain, space.organization, space |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List routes for an app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/routes" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
+ "protocol": "http",
+ "created_at": "2019-05-10T17:17:48Z",
+ "updated_at": "2019-05-10T17:17:48Z",
+ "host": "a-hostname",
+ "path": "/some_path",
+ "url": "a-hostname.a-domain.com/some_path",
+ "destinations": [
+ {
+ "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
+ "app": {
+ "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "http1"
+ },
+ {
+ "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
+ "app": {
+ "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "http1"
+ }
+ ],
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
+ }
+ },
+ "domain": {
+ "data": {
+ "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
+ },
+ "domain": {
+ "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
+ },
+ "destinations": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all routes that have destinations that point to the given app.
+ +Definition
+ +GET /v3/apps/:guid/routes
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| domain_guids | +list of strings | +Comma-delimited list of domain guids to filter by | +
| hosts | +list of strings | +Comma-delimited list of hostnames to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| paths | +list of strings | +Comma-delimited list of paths to filter by (e.g. /path1,/path2) |
+
| ports | +list of integers | +Comma-delimited list of ports to filter by (e.g. 3306,5432) |
+
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update a route
+Example Request
+curl "https://api.example.org/v3/routes/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "metadata": {
+ "labels": {"key": "value"},
+ "annotations": {"note": "detailed information"}
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
+ "protocol": "tcp",
+ "port": 6666,
+ "created_at": "2019-05-10T17:17:48Z",
+ "updated_at": "2019-05-10T17:17:48Z",
+ "host": "a-hostname",
+ "path": "/some_path",
+ "url": "a-hostname.a-domain.com/some_path",
+ "destinations": [
+ {
+ "guid": "385bf117-17f5-4689-8c5c-08c6cc821fed",
+ "app": {
+ "guid": "0a6636b5-7fc4-44d8-8752-0db3e40b35a5",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "tcp"
+ },
+ {
+ "guid": "27e96a3b-5bcf-49ed-8048-351e0be23e6f",
+ "app": {
+ "guid": "f61e59fa-2121-4217-8c7b-15bfd75baf25",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "tcp"
+ }
+ ],
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
+ }
+ },
+ "domain": {
+ "data": {
+ "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236"
+ },
+ "domain": {
+ "href": "https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e"
+ },
+ "destinations": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/routes/:guid
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| metadata.labels | +label object | +Labels applied to the route | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the route | ++ |
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Delete a route
+Example Request
+curl "https://api.example.org/v3/routes/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/routes/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Check reserved routes for a domain
+Example Request
+curl "https://api.example.org/v3/domains/[guid]/route_reservations" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "matching_route": true
+}
+
+Check if a specific route for a domain exists, regardless of the user’s visibility for the route in case the route +belongs to a space the user does not belong to.
+ +Definition
+ +GET /v3/domains/:guid/route_reservations
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| host | +string | +Hostname to filter by; defaults to empty string if not provided and only applicable to http routes |
+
| path | +string | +Path to filter by; defaults to empty string if not provided and only applicable to http routes |
+
| port | +integer | +Port to filter by; only applicable to tcp routes and required for tcp routes |
+
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Auditor | ++ |
| Org Billing Manager | +Can only check if routes exist for a domain without an organization relationship | +
| Org Manager | ++ |
| Space Auditor | ++ |
| Space Developer | ++ |
| Space Manager | ++ |
| Space Supporter | ++ |
Lists shared spaces relationship (experimental)
+ +Lists the spaces that the route has been shared to.
+Example Request
+curl "https://api.example.org/v3/routes/[guid]/relationships/shared_spaces" \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json"
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ { "guid": "space-one-guid" },
+ { "guid": "space-two-guid" }
+ ],
+ "links": {
+ "self": {
+ "href":"http://api.example.com/v3/routes/[guid]/relationships/shared_spaces"
+ }
+ }
+}
+Definition
+ +GET /v3/routes/:guid/relationships/shared_spaces
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Share a route with other spaces (experimental)
+ +This endpoint shares the route with the specified spaces. This allows users with read and write access in both the route’s space and a shared space to bind a route to an app in the shared space. In order to share into a space the requesting user must have write permission in the target space.
+Example Request
+curl "https://api.example.org/v3/routes/[guid]/relationships/shared_spaces" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": [
+ { "guid": "space-one-guid" },
+ { "guid": "space-two-guid" }
+ ]
+ }'
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ { "guid": "space-one-guid" },
+ { "guid": "space-two-guid" }
+ ],
+ "links": {
+ "self": {
+ "href":"http://api.example.com/v3/routes/[guid]/relationships/shared_spaces"
+ }
+ }
+}
+Definition
+ +POST /v3/routes/:guid/relationships/shared_spaces
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-many relationship | +Shared space relationships; each space will have this route shared to it | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Unshare a route that was shared with another space (experimental)
+ +Unshares a route that was shared with another space.
+Example Request
+curl "https://api.example.org/v3/routes/:guid/relationships/shared_spaces/[space_guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json"
+HTTP/1.1 204 No Content
+Definition
+ +DELETE /v3/routes/:guid/relationships/shared_spaces/:space_guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Transfer ownership (experimental)
+ +Transfers a the ownership of a route to a another space. Users must have write access for both spaces to perform this action. +The original owning space will still retain access to the route as a shared space. +To completely remove a space from a route, users will have to use unshare route.
+Example Request
+curl "https://api.example.org/v3/routes/:route-guid/relationships/space" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json"
+ -d '{ "data": { "guid": "space-guid"} }'
+Example Response
+HTTP/1.1 204 No Content
+Definition
+ +PATCH /v3/routes/:route-guid/relationships/space
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
List destinations for a route
+Example Request
+curl "https://api.example.org/v3/routes/[guid]/destinations" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "destinations": [
+ {
+ "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
+ "app": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "http2"
+ },
+ {
+ "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
+ "app": {
+ "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
+ "process": {
+ "type": "api"
+ }
+ },
+ "weight": null,
+ "port": 9000,
+ "protocol": "http1"
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ }
+ }
+ }
+
+Retrieve all destinations associated with a route.
+ +Definition
+ +GET /v3/routes/:guid/destinations
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of destination guids to filter by | +
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Insert destinations for a route
+Example Request
+curl "https://api.example.org/v3/routes/[guid]/destinations" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+ -H "Content-type: application/json"
+ -d '{
+ "destinations": [
+ {
+ "app": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ },
+ {
+ "app": {
+ "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
+ "process": {
+ "type": "api"
+ }
+ },
+ "port": 9000,
+ "protocol": "http1"
+ }
+ ]
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "destinations": [
+ {
+ "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
+ "app": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": null,
+ "port": 8080,
+ "protocol": "http2"
+ },
+ {
+ "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
+ "app": {
+ "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
+ "process": {
+ "type": "api"
+ }
+ },
+ "weight": null,
+ "port": 9000,
+ "protocol": "http1"
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ }
+ }
+ }
+
+Add one or more destinations to a route, preserving any existing destinations.
+ +Weighted destinations (deprecated) cannot be added with this endpoint.
+ +Definition
+ +POST /v3/routes/:guid/destinations
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| destinations | +array of destination objects | +List of destinations to add to route; destinations without process.type specified will get process type "web" by default |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Replace all destinations for a route
+Example Request
+curl "https://api.example.org/v3/routes/[guid]/destinations" \
+ -X PATCH \
+ -H "Authorization: bearer [token]"
+ -d '{
+ "destinations": [
+ {
+ "app": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "weight": 61
+ },
+ {
+ "app": {
+ "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
+ "process": {
+ "type": "api"
+ }
+ },
+ "weight": 39,
+ "port": 9000,
+ "protocol": "http1"
+ }
+ ]
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "destinations": [
+ {
+ "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
+ "app": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": 61,
+ "port": 8080,
+ "protocol": "http2"
+ },
+ {
+ "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
+ "app": {
+ "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
+ "process": {
+ "type": "api"
+ }
+ },
+ "weight": 39,
+ "port": 9000,
+ "protocol": "http1"
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ }
+ }
+}
+Replaces all destinations for a route, removing any destinations not included in the provided list.
+ +Weighted destinations are deprecated. Development of the experimental Istio Service Mesh routing layer
+was discontinued in 2020 and is no longer supported by the platform. Specifying a weight for a destination will take no effect.
If weighted destinations are provided, however, all destinations provided here must have a weight specified, and all weights
+for this route must sum to 100. If not, all provided destinations must not have a weight. Mixing weighted
+and unweighted destinations for a route is not allowed.
Definition
+ +PATCH /v3/routes/:guid/destinations
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| destinations | +array of destination objects | +List of destinations use for route. Destinations without process.type specified will get process type "web" by default |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Update a destination protocol for a route
+Example Request
+curl "https://api.example.org/v3/routes/[guid]/destinations/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]"
+ -d '{"protocol": "http2"}'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
+ "app": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "process": {
+ "type": "web"
+ }
+ },
+ "weight": 61,
+ "port": 8080,
+ "protocol": "http2",
+ "links": {
+ "destinations": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31"
+ }
+ }
+}
+This endpoint updates the protocol of a route destination (app, port and weight cannot be updated)
+ +Definition
+ +PATCH /v3/routes/:guid/destinations/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| protocol | +string or null |
+Protocol the destination will use. Valid protocols are http1 or http2 if route protocol is http, tcp if route protocol is tcp. A null value will set it to either http1 or tcp based on the route protocol; |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Remove destination for a route
+Example Request
+curl "https://api.example.org/v3/routes/[guid]/destinations/[destination_guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+Remove a destination from a route.
+ +Definition
+ +DELETE /v3/routes/:guid/destinations/:destination_guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Delete unmapped routes for a space
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/routes?unmapped=true" \
+ -X DELETE\
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Deletes all routes in a space that are not mapped to any applications and not bound to any service instances.
+ +Definition
+ +DELETE /v3/spaces/:guid/routes?unmapped=true
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Note: unmapped=true is a required query parameter; always include it.
Security Groups
+ +Security groups are collections of egress traffic rules that can be applied to the staging or running state of applications.
+ +Security groups can either be applied globally or at the space-level.
+ +Security groups can only allow (whitelist) traffic. They cannot be used to disallow (blacklist) traffic.
+The security group object
+Example Security Group object
+{
+ "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group0",
+ "globally_enabled": {
+ "running": true,
+ "staging": false
+ },
+ "rules": [
+ {
+ "protocol": "tcp",
+ "destination": "10.10.10.0/24",
+ "ports": "443,80,8080"
+ },
+ {
+ "protocol": "icmp",
+ "destination": "10.10.10.0/24",
+ "type": 8,
+ "code": 0,
+ "description": "Allow ping requests to private services"
+ },
+ {
+ "protocol": "tcp",
+ "destination": "1.1.1.1,2.2.2.2/24,10.0.0.0-10.0.0.255",
+ "ports": "80,443,8080",
+ "description": "Only valid if cc.security_groups.enable_comma_delimited_destinations is true"
+ }
+ ],
+ "relationships": {
+ "staging_spaces": {
+ "data": [
+ { "guid": "space-guid-1" },
+ { "guid": "space-guid-2" }
+ ]
+ },
+ "running_spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the security group | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the security group | +
| rules | +array of rule objects | +Rules that will be applied by this security group | +
| globally_enabled | +object | +Object that controls if the group is applied globally to the lifecycle of all applications | +
| globally_enabled.running | +boolean | +Specifies whether the group should be applied globally to all running applications | +
| globally_enabled.staging | +boolean | +Specifies whether the group should be applied globally to all staging applications | +
| relationships.running_spaces | +to-many relationship | +A relationship to the spaces where the security_group is applied to applications during runtime | +
| relationships.staging_spaces | +to-many relationship | +A relationship to the spaces where the security_group is applied to applications during staging | +
| links | +links object | +Links to related resources | +
The rule object
+ +| Name | +Type | +Description | +Required | +Default | +
|---|---|---|---|---|
| protocol | +string | +Protocol type Valid values are tcp, udp, icmp, or all |
+yes | +N/A | +
| destination | +string | +The destination where the rule applies. Must be a singular Valid CIDR, IP address, or IP address range unless cc.security_groups.enable_comma_delimited_destinations is enabled. Then, the destination can be a comma-delimited string of CIDRs, IP addresses, or IP address ranges. Octets within destinations cannot contain leading zeros; eg. 10.0.0.0/24 is valid, but 010.00.000.0/24 is not. |
+yes | +N/A | +
| ports | +string | +Ports that the rule applies to; can be a single port (9000), a comma-separated list (9000,9001), or a range (9000-9200) |
+no | +null |
+
| type | +integer | +Type required for ICMP protocol; valid values are between -1 and 255 (inclusive), where -1 allows all | +no | +null |
+
| code | +integer | +Code required for ICMP protocol; valid values are between -1 and 255 (inclusive), where -1 allows all | +no | +null |
+
| description | +string | +A description for the rule; this field is limited to 16MB | +no | +null |
+
| log | +boolean | +Enable logging for rule, only valid for tcp rules | +no | +null |
+
Create a security group
+Example Request
+curl "https://api.example.org/v3/security_groups" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my-group0",
+ "rules": [
+ {
+ "protocol": "tcp",
+ "destination": "10.10.10.0/24",
+ "ports": "443,80,8080"
+ },
+ {
+ "protocol": "icmp",
+ "destination": "10.10.10.0/24",
+ "type": 8,
+ "code": 0,
+ "description": "Allow ping requests to private services"
+ }
+ ]
+}'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group0",
+ "globally_enabled": {
+ "running": true,
+ "staging": false
+ },
+ "rules": [
+ {
+ "protocol": "tcp",
+ "destination": "10.10.10.0/24",
+ "ports": "443,80,8080"
+ },
+ {
+ "protocol": "icmp",
+ "destination": "10.10.10.0/24",
+ "type": 8,
+ "code": 0,
+ "description": "Allow ping requests to private services"
+ },
+ {
+ "protocol": "tcp",
+ "destination": "1.1.1.1,2.2.2.2/24,10.0.0.0-10.0.0.255",
+ "ports": "80,443,8080",
+ "description": "Only valid if cc.security_groups.enable_comma_delimited_destinations is true"
+ }
+ ],
+ "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"
+ },
+ {
+ "protocol": "tcp",
+ "destination": "1.1.1.1,2.2.2.2/24,10.0.0.0-10.0.0.255",
+ "ports": "80,443,8080",
+ "description": "Only valid if cc.security_groups.enable_comma_delimited_destinations is true"
+ }
+ ],
+ "relationships": {
+ "staging_spaces": {
+ "data": [
+ { "guid": "space-guid-1" },
+ { "guid": "space-guid-2" }
+ ]
+ },
+ "running_spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
+ }
+ }
+}
+
+Definition
+ +GET /v3/security_groups/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | +Can see all security groups | +
| Admin Read-Only | +Can see all security groups | +
| Global Auditor | +Can see all security groups | +
| Org Auditor | +Can see globally enabled security groups | +
| Org Billing Manager | +Can see globally enabled security groups | +
| Org Manager | +Can see globally enabled security groups or groups associated with a space they can see | +
| Space Auditor | +Can see globally enabled security groups or groups associated with a space they can see | +
| Space Developer | +Can see globally enabled security groups or groups associated with a space they can see | +
| Space Manager | +Can see globally enabled security groups or groups associated with a space they can see | +
| Space Supporter | +Can see globally enabled security groups or groups associated with a space they can see | +
List security groups
+Example Request
+curl "https://api.example.org/v3/security_groups" \
+ -X GET \
+ -H "Authorization: bearer [token]" \
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/security_groups?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/security_groups?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group0",
+ "globally_enabled": {
+ "running": true,
+ "staging": false
+ },
+ "rules": [
+ {
+ "protocol": "tcp",
+ "destination": "10.10.10.0/24",
+ "ports": "443,80,8080"
+ },
+ {
+ "protocol": "icmp",
+ "destination": "10.10.10.0/24",
+ "type": 8,
+ "code": 0,
+ "description": "Allow ping requests to private services"
+ }
+ ],
+ "relationships": {
+ "staging_spaces": {
+ "data": [
+ { "guid": "space-guid-1" },
+ { "guid": "space-guid-2" }
+ ]
+ },
+ "running_spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
+ }
+ }
+ },
+ {
+ "guid": "a89a788e-671f-4549-814d-e34c1b2f533a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group1",
+ "globally_enabled": {
+ "running": true,
+ "staging": true
+ },
+ "rules": [],
+ "relationships": {
+ "staging_spaces": {
+ "data": []
+ },
+ "running_spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a"
+ }
+ }
+ }
+ ]
+}
+
+Definition
+ +GET /v3/security_groups
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of security group guids to filter by | +
| names | +list of strings | +Comma-delimited list of security group names to filter by | +
| globally_enabled_running | +boolean | +If true, only include the security groups that are enabled for running | +
| globally_enabled_staging | +boolean | +If true, only include the security groups that are enabled for staging | +
| running_space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| staging_space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | +Can see all security groups | +
| Admin Read-Only | +Can see all security groups | +
| Global Auditor | +Can see all security groups | +
| Org Auditor | +Can see globally–enabled security groups | +
| Org Billing Manager | +Can see globally–enabled security groups | +
| Org Manager | +Can see globally–enabled security groups or groups associated with a space they can see | +
| Space Auditor | +Can see globally–enabled security groups or groups associated with a space they can see | +
| Space Developer | +Can see globally–enabled security groups or groups associated with a space they can see | +
| Space Manager | +Can see globally–enabled security groups or groups associated with a space they can see | +
| Space Supporter | +Can see globally–enabled security groups or groups associated with a space they can see | +
Update a security group
+Example Request
+curl "https://api.example.org/v3/security_groups/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my-group0",
+ "globally_enabled": {
+ "running": true
+ }
+ "rules": [
+ {
+ "protocol": "tcp",
+ "destination": "10.10.10.0/24",
+ "ports": "443,80,8080"
+ },
+ {
+ "protocol": "icmp",
+ "destination": "10.10.10.0/24",
+ "type": 8,
+ "code": 0,
+ "description": "Allow ping requests to private services"
+ }
+ ]
+}'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group0",
+ "globally_enabled": {
+ "running": true,
+ "staging": false
+ },
+ "rules": [
+ {
+ "protocol": "tcp",
+ "destination": "10.10.10.0/24",
+ "ports": "443,80,8080"
+ },
+ {
+ "protocol": "icmp",
+ "destination": "10.10.10.0/24",
+ "type": 8,
+ "code": 0,
+ "description": "Allow ping requests to private services"
+ },
+ {
+ "protocol": "tcp",
+ "destination": "1.1.1.1,2.2.2.2/24,10.0.0.0-10.0.0.255",
+ "ports": "80,443,8080",
+ "description": "Only valid if cc.security_groups.enable_comma_delimited_destinations is true"
+ }
+ ],
+ "relationships": {
+ "staging_spaces": {
+ "data": [
+ { "guid": "space-guid-1" },
+ { "guid": "space-guid-2" }
+ ]
+ },
+ "running_spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
+ }
+ }
+}
+
+This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values.
+ +Updates to the rules parameter will fully replace the current set of rules for the security group.
Updates to the globally_enabled parameter will be merged with the existing configuration. For example, an update to the globally_enabled.running parameter will not affect the globally_enabled.staging configuration.
Definition
+ +PATCH /v3/security_groups/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the security group | +
| globally_enabled | +object | +Object that controls if the group is applied globally to the lifecycle of all applications | +
| globally_enabled.running | +boolean | +Specifies whether the group should be applied globally to all running applications | +
| globally_enabled.staging | +boolean | +Specifies whether the group should be applied globally to all staging applications | +
| rules | +array of rule objects | +Rules that will be applied by this security group | +
Permitted roles
+ +| + |
|---|
| Admin | +
Delete a security group
+Example Request
+curl "https://api.example.org/v3/security_groups/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+
+Definition
+ +DELETE /v3/security_groups/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
Bind a running security group to spaces
+Example Request
+curl "https://api.example.org/v3/security_groups/[guid]/relationships/running_spaces" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": [{ "guid": "space-guid1" }, { "guid": "space-guid2" }]
+}'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ { "guid": "space-guid1" },
+ { "guid": "space-guid2" },
+ { "guid": "previous-space-guid" }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a/relationships/running_spaces"
+ }
+ }
+}
+
+This endpoint binds one or more spaces to a security group with the running lifecycle.
+ +Running app containers within these spaces will inherit the rules specified by this security group.
+ +Apps within these spaces must be restarted for these changes to take effect.
+ +Unless a security group is globally-enabled, an admin must add it to a space for it to be visible for the org and space managers. Once it’s visible, org and space managers can add it to additional spaces.
+ +Definition
+ +POST /v3/security_groups/:guid/relationships/running_spaces
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-many relationship | +Space guids that will be bound to the security group | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Manager | +Can bind visible security groups to their spaces (visible groups are globally–enabled security groups or groups associated with a space they can see) | +
| Org Manager | +Can bind visible security groups to their organizations’ spaces (visible groups are globally–enabled security groups or groups associated with a space they can see) | +
Bind a staging security group to spaces
+Example Request
+curl "https://api.example.org/v3/security_groups/[guid]/relationships/staging_spaces" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": [{ "guid": "space-guid1" }, { "guid": "space-guid2" }]
+}'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ { "guid": "space-guid1" },
+ { "guid": "space-guid2" },
+ { "guid": "previous-space-guid" }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a/relationships/staging_spaces"
+ }
+ }
+}
+
+This endpoint binds one or more spaces to a security group with the staging lifecycle.
+ +Staging app containers within these spaces will inherit the rules specified by this security group.
+ +Apps within these spaces must be restaged for these changes to take effect.
+ +Unless a security group is globally-enabled, an admin must add it to a space for it to be visible for the org and space managers. Once it’s visible, org and space managers can add it to additional spaces.
+ +Definition
+ +POST /v3/security_groups/:guid/relationships/staging_spaces
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-many relationship | +Space guids that will be bound to the security group | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Manager | +Can bind visible security groups to their spaces (visible groups are globally–enabled security groups or groups associated with a space they can see) | +
| Org Manager | +Can bind visible security groups to their organizations’ spaces (visible groups are globally–enabled security groups or groups associated with a space they can see) | +
Unbind a running security group from a space
+Example Request
+curl "https://api.example.org/v3/security_groups/[guid]/relationships/running_spaces/[space_guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+Content-Type: application/json
+This endpoint removes a space from a security group with the running lifecycle.
+ +Apps within this space must be restarted for these changes to take effect.
+ +Definition
+ +DELETE /v3/security_groups/:guid/relationships/running_spaces/:space_guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Manager | +Can unbind visible security groups from their spaces (visible groups are globally–enabled security groups or groups associated with a space they can see) | +
| Org Manager | +Can unbind visible security groups from their organizations’ spaces (visible groups are globally–enabled security groups or groups associated with a space they can see) | +
Unbind a staging security group from a space
+Example Request
+curl "https://api.example.org/v3/security_groups/[guid]/relationships/staging_spaces/[space_guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+Content-Type: application/json
+This endpoint removes a space from a security group with the staging lifecycle.
+ +Apps within this space must be restaged for these changes to take effect.
+ +Definition
+ +DELETE /v3/security_groups/:guid/relationships/staging_spaces/:space_guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Manager | +Can unbind visible security groups from their spaces (visible groups are globally–enabled security groups or groups associated with a space they can see) | +
| Org Manager | +Can unbind visible security groups from their organizations’ spaces (visible groups are globally–enabled security groups or groups associated with a space they can see) | +
List running security groups for a space
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/running_security_groups" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/running_security_groups?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/running_security_groups?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group0",
+ "globally_enabled": {
+ "running": true,
+ "staging": false
+ },
+ "rules": [
+ {
+ "protocol": "tcp",
+ "destination": "10.10.10.0/24",
+ "ports": "443,80,8080"
+ },
+ {
+ "protocol": "icmp",
+ "destination": "10.10.10.0/24",
+ "type": 8,
+ "code": 0,
+ "description": "Allow ping requests to private services"
+ }
+ ],
+ "relationships": {
+ "staging_spaces": {
+ "data": []
+ },
+ "running_spaces": {
+ "data": [
+ { "guid": "space-guid-1" },
+ { "guid": "space-guid-2" }
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
+ }
+ }
+ },
+ {
+ "guid": "a89a788e-671f-4549-814d-e34c1b2f533a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group1",
+ "globally_enabled": {
+ "running": true,
+ "staging": true
+ },
+ "rules": [],
+ "relationships": {
+ "staging_spaces": {
+ "data": []
+ },
+ "running_spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint returns security groups that are enabled for running globally or at the space level for the given space.
+ +Definition
+ +GET /v3/spaces/:guid/running_security_groups
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of security group guids to filter by | +
| names | +list of strings | +Comma-delimited list of security group names to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | +Can see all security groups | +
| Admin Read-Only | +Can see all security groups | +
| Global Auditor | +Can see all security groups | +
| Org Manager | +Can see globally-enabled security groups and groups associated with spaces in their managed organizations | +
| Space Auditor | +Can see globally-enabled security groups and groups associated with spaces where they have this role | +
| Space Developer | +Can see globally-enabled security groups and groups associated with spaces where they have this role | +
| Space Manager | +Can see globally-enabled security groups and groups associated with spaces where they have this role | +
| Space Supporter | +Can see globally-enabled security groups and groups associated with spaces where they have this role | +
List staging security groups for a space
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/staging_security_groups" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 1,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/staging_security_groups?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/staging_security_groups?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "b85a788e-671f-4549-814d-e34cdb2f539a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group0",
+ "globally_enabled": {
+ "running": false,
+ "staging": true
+ },
+ "rules": [
+ {
+ "protocol": "tcp",
+ "destination": "10.10.10.0/24",
+ "ports": "443,80,8080"
+ },
+ {
+ "protocol": "icmp",
+ "destination": "10.10.10.0/24",
+ "type": 8,
+ "code": 0,
+ "description": "Allow ping requests to private services"
+ }
+ ],
+ "relationships": {
+ "staging_spaces": {
+ "data": [
+ { "guid": "space-guid-1" },
+ { "guid": "space-guid-2" }
+ ]
+ },
+ "running_spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a"
+ }
+ }
+ },
+ {
+ "guid": "a89a788e-671f-4549-814d-e34c1b2f533a",
+ "created_at": "2020-02-20T17:42:08Z",
+ "updated_at": "2020-02-20T17:42:08Z",
+ "name": "my-group1",
+ "globally_enabled": {
+ "running": true,
+ "staging": true
+ },
+ "rules": [],
+ "relationships": {
+ "staging_spaces": {
+ "data": []
+ },
+ "running_spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint returns security groups that are enabled for staging globally or at the space level for the given space.
+ +Definition
+ +GET /v3/spaces/:guid/staging_security_groups
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of security group guids to filter by | +
| names | +list of strings | +Comma-delimited list of security group names to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | +Can see all security groups | +
| Admin Read-Only | +Can see all security groups | +
| Global Auditor | +Can see all security groups | +
| Org Manager | +Can see globally-enabled security groups and groups associated with spaces in their managed organizations | +
| Space Auditor | +Can see globally-enabled security groups and groups associated with spaces where they have this role | +
| Space Developer | +Can see globally-enabled security groups and groups associated with spaces where they have this role | +
| Space Manager | +Can see globally-enabled security groups and groups associated with spaces where they have this role | +
| Space Supporter | +Can see globally-enabled security groups and groups associated with spaces where they have this role | +
Service Brokers
+ +Service brokers manage the lifecycle of services. On behalf of users, Cloud Controller will interact with service brokers to provision, get access to and manage access to the service offerings and plans they offer.
+ +Admins can create and manage service brokers that are globally available, i.e., the service broker and its associated resources (service offerings and plans) can be made available to all users.
+ +Space Developers can create and manage space-scoped service brokers. A space-scoped broker and its associated resources will only be available in the space the service broker was created.
+The service broker object
+Example Service Broker object
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "name": "my_service_broker",
+ "url": "https://example.service-broker.com",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {
+ "type": "dev"
+ },
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "service_offerings": {
+ "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the service broker | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the service broker | +
| url | +string | +URL of the service broker | +
| relationships.space | +to-one relationship | +The space the service broker is restricted to; omitted for globally available service brokers | +
| metadata.labels | +label object | +Labels applied to the service broker | +
| metadata.annotations | +annotation object | +Annotations added to the service broker | +
| links | +links object | +Links to related resources | +
Create a service broker
+Example Request
+curl "https://api.example.org/v3/service_brokers" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my_service_broker",
+ "url": "https://example.service-broker.com",
+ "authentication": {
+ "type": "basic",
+ "credentials": {
+ "username": "us3rn4me",
+ "password": "p4ssw0rd"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+This endpoint creates a new service broker and a job to synchronize the service offerings and service plans with those in the broker’s catalog.
+The Location header refers to the created job which syncs the broker with the catalog. See Service broker jobs for more information and limitations.
Definition
+ +POST /v3/service_brokers
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the service broker | +
| url | +string | +URL of the service broker | +
| authentication | +authentication | +Credentials used to authenticate against the service broker | +
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| relationships.space | +to-one relationship | +If set, restricts the service broker to the specified space | +
| metadata.labels | +label object | +Labels applied to the service broker | +
| metadata.annotations | +annotation object | +Annotations applied to the service broker | +
The authentication object
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Type of the authentication mechanisms that can be used. Valid value is basic. |
+
| credentials | +object | +Credentials for given authentication type. | +
Example basic authentication
+{
+ "type": "basic",
+ "credentials": {
+ "username": "admin",
+ "password": "secretpassw0rd"
+ }
+}
+Basic authentication credentials
+ +| Name | +Type | +Description | +
|---|---|---|
| username | +string | +The username with which to authenticate against the service broker. | +
| password | +string | +The password with which to authenticate against the service broker. | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer* | +
*Space Developers can only create space-scoped brokers. Space-scoped brokers can only be created when the space_scoped_private_broker_creation feature flag is true.
Get a service broker
+Example Request
+curl "https://api.example.org/v3/service_brokers/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "name": "my_service_broker",
+ "url": "https://example.service-broker.com",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {
+ "type": "dev"
+ },
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "service_offerings": {
+ "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+}
+
+This endpoint retrieves the service broker by GUID.
+ +Definition
+ +GET /v3/service_brokers/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Space Developer | +Only space-scoped brokers | +
| Space Supporter | +Only space-scoped brokers | +
List service brokers
+Example Request
+curl "https://api.example.org/v3/service_brokers" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/service_brokers?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "name": "my_service_broker",
+ "url": "https://example.service-broker.com",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {} ,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "service_offerings": {
+ "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ }
+ }
+ },
+ {
+ "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
+ "name": "another_service_broker",
+ "url": "https://another-example.service-broker.com",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_brokers/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
+ },
+ "service_offerings": {
+ "href": "https://api.example.org/v3/service_offerings?service_broker_guids=7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint retrieves the service brokers the user has access to.
+ +Definition
+ +GET /v3/service_brokers
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of service broker names to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| space_guids | +list of strings | +Comma-delimited list of space GUIDs to filter by | +
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at, name |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Space Developer | +Only space-scoped brokers | +
| Space Supporter | +Only space-scoped brokers | +
| Other | +Will receive an empty list | +
Update a service broker
+Example Request
+curl "https://api.example.org/v3/service_brokers/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my_service_broker",
+ "url": "https://example.service-broker.com",
+ "authentication": {
+ "type": "basic",
+ "credentials": {
+ "username": "us3rn4me",
+ "password": "p4ssw0rd"
+ }
+ },
+ "metadata": {
+ "labels": {"key": "value"},
+ "annotations": {"note": "detailed information"}
+ }
+ }'
+Example Response with job
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+Example Response without job
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "name": "my_service_broker",
+ "url": "https://example.service-broker.com",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {
+ "type": "dev"
+ },
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "service_offerings": {
+ "href": "https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ }
+}
+
+This endpoint updates a service broker. Depending on the parameters specified, +the endpoint may respond with a background job, and it may synchronize the +service offerings and service plans with those in the broker’s catalog.
+ +When a service broker has a synchronization job in progress, only
+updates with metadata are permitted until the synchronization job
+is complete.
| Parameter | +Updates Catalog | +Responds with job | +
|---|---|---|
| name | +No | +Yes | +
| url | +Yes | +Yes | +
| authentication | +Yes | +Yes | +
| metadata.labels | +No | +No | +
| metadata.annotations | +No | +No | +
Definition
+ +PATCH /v3/service_brokers/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the service broker | +
| url | +string | +URL of the service broker | +
| authentication | +authentication | +Credentials used to authenticate against the service broker | +
| metadata.labels | +label object | +Labels applied to the service broker | +
| metadata.annotations | +annotation object | +Annotations applied to the service broker | +
The authentication object
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Type of the authentication mechanisms that can be used. Valid value is basic. |
+
| credentials | +object | +Credentials for given authentication type. | +
Example basic authentication
+{
+ "type": "basic",
+ "credentials": {
+ "username": "admin",
+ "password": "secretpassw0rd"
+ }
+}
+Basic authentication credentials
+ +| Name | +Type | +Description | +
|---|---|---|
| username | +string | +The username with which to authenticate against the service broker. | +
| password | +string | +The password with which to authenticate against the service broker. | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | +Only space-scoped brokers | +
Delete a service broker
+Example Request
+curl "https://api.example.org/v3/service_brokers/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+This endpoint creates a job to delete an existing service broker. The Location header refers to the created job. See Service broker jobs for more information and limitations.
Definition
+ +DELETE /v3/service_brokers/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | +Only space-scoped brokers | +
Service broker jobs
+ +CRUD operations for service brokers are asynchronous. create, update and delete endpoints include a job URL in the Location header of the HTTP response.
These jobs are the only source of information about the progress of the operation. Therefore, the job must be polled to find out when the process ends and if it was successful.
+There is no mechanism to link a service broker with its jobs, apart from the Location header in the API response.
When a failure occurs during a create job, the service broker won’t be usable. It will still be included in the GET endpoints responses, hence the importance of querying the job to find out the end status.
When updating a service broker, catalog changes will be rolled-back in the event of the job failing. The service broker catalog will remain unchanged with no indication that the update operation failed. Querying the job will provide such information.
+Service Offerings
+ +Service offerings represent the services offered by service brokers. +A service broker will have one or more service offerings. +A service offering will have one or more service plans. +Service offerings and service plans are created and updated when a service broker is registered or updated.
+Visibility of service offerings
+ +This table shows the service offerings that different roles can see. +The service offerings that a user can see relate to their space and organization roles, +regardless of which space or organization is being targeted.
+ +A service offering can be seen when at least one of its service plans can be seen.
+Service plans may be configured to be public,
+or they may be configured with a relationship to a restricted list of organizations.
Service offerings and service plans from a space-scoped service broker cannot have their visibility configured. +They are only visible to members of that space.
+ +| Role | +Public plans | +Restricted plans | +From space-scoped service brokers | +
|---|---|---|---|
| Admin | +All | +All | +All | +
| Admin Read | +All | +All | +All | +
| Global Auditor | +All | +All | +All | +
| Org Manager | +All | +In organisation | +None | +
| Org Auditor | +All | +In organisation | +None | +
| Org Billing | +All | +In organisation | +None | +
| Space Manager | +All | +In organisation | +In space | +
| Space Developer | +All | +In organisation | +In space | +
| Space Auditor | +All | +In organisation | +In space | +
| Unauthenticated | +All* | +None | +None | +
*Unless the hide_marketplace_from_unauthenticated_users feature flag is true
The service offering object
+Example Service Offering object
+{
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_service_offering",
+ "description": "Provides my service",
+ "available": true,
+ "tags": ["relational", "caching"],
+ "requires": [],
+ "created_at": "2019-11-28T13:44:02Z",
+ "updated_at": "2019-11-28T13:44:02Z",
+ "shareable": true,
+ "documentation_url": "https://some-documentation-link.io",
+ "broker_catalog": {
+ "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
+ "metadata": {
+ "shareable": true
+ },
+ "features": {
+ "plan_updateable": true,
+ "bindable": true,
+ "instances_retrievable": true,
+ "bindings_retrievable": true,
+ "allow_context_updates": false
+ }
+ },
+ "relationships": {
+ "service_broker": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
+ },
+ "service_plans": {
+ "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
+ },
+ "service_broker": {
+ "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+}
+
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the service offering | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the service offering | +
| description | +string | +Description of the service offering | +
| available | +boolean | +Whether or not the service offering is available | +
| tags | +list of strings | +Descriptive tags for the service offering | +
| requires | +list of strings | +A list of permissions that the user would have to give the service, if they provision it; the only permissions currently supported are syslog_drain, route_forwarding and volume_mount |
+
| shareable | +boolean | +Whether or not service Instances of this service offering can be shared across organizations and spaces | +
| documentation_url | +string | +Url that points to a documentation page for the service offering, if provided by the service broker as part of the metadata field | +
| broker_catalog | +broker catalog object | +This object contains information obtained from the service broker Catalog | +
| relationships.service_broker | +to-one relationship | +The service broker that provides this service offering | +
| metadata.labels | +label object | +Labels applied to the service offering | +
| metadata.annotations | +annotation object | +Annotations added to the service offering | +
| links | +links object | +Links to related resources | +
The service offering broker catalog
+ +| Name | +Type | +Description | +
|---|---|---|
| id | +string | +The identifier that the service broker provided for this service offering | +
| metadata | +object | +Additional information provided by the service broker as specified by OSBAPI | +
| features.plan_updateable | +boolean | +Whether the service offering supports upgrade/downgrade for service plans by default; service plans can override this field | +
| features.bindable | +boolean | +Specifies whether service Instances of the service can be bound to applications | +
| features.instances_retrievable | +boolean | +Specifies whether the Fetching a service instance endpoint is supported for all service plans | +
| features.bindings_retrievable | +boolean | +Specifies whether the Fetching a service binding endpoint is supported for all service plans | +
| features.allow_context_updates | +boolean | +Specifies whether service instance updates relating only to context are propagated to the service broker | +
Get a service offering
+Example Request
+curl "https://api.example.org/v3/service_offerings/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_service_offering",
+ "description": "Provides my service",
+ "available": true,
+ "tags": ["relational", "caching"],
+ "requires": [],
+ "created_at": "2019-11-28T13:44:02Z",
+ "updated_at": "2019-11-28T13:44:02Z",
+ "shareable": true,
+ "documentation_url": "https://some-documentation-link.io",
+ "broker_catalog": {
+ "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
+ "metadata": {
+ "shareable": true
+ },
+ "features": {
+ "plan_updateable": true,
+ "bindable": true,
+ "instances_retrievable": true,
+ "bindings_retrievable": true,
+ "allow_context_updates": false
+ }
+ },
+ "relationships": {
+ "service_broker": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
+ },
+ "service_plans": {
+ "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
+ },
+ "service_broker": {
+ "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+}
+
+
+This endpoint retrieves the service offering by GUID.
+ +Definition
+ +GET /v3/service_offerings/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| fields | +fields parameter | +Allowed values | +
Service Offering Fields
+ +| Resource | +Allowed Keys | +
|---|---|
| service_broker | +guid, name |
+
Permitted roles
+ +| + |
|---|
| All Roles | +
Unauthenticated Users (for service offerings with public plans, unless hide_marketplace_from_unauthenticated_users is set) |
+
List service offerings
+Example Request
+curl "https://api.example.org/v3/service_offerings" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/service_offerings?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/service_offerings?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/service_offerings?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_service_offering",
+ "description": "Provides my service",
+ "available": true,
+ "tags": ["relational", "caching"],
+ "requires": [],
+ "created_at": "2019-11-28T13:44:02Z",
+ "updated_at": "2019-11-28T13:44:02Z",
+ "shareable": true,
+ "documentation_url": "https://some-documentation-link.io",
+ "broker_catalog": {
+ "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
+ "metadata": {
+ "shareable": true
+ },
+ "features": {
+ "plan_updateable": true,
+ "bindable": true,
+ "instances_retrievable": true,
+ "bindings_retrievable": true,
+ "allow_context_updates": false
+ }
+ },
+ "relationships": {
+ "service_broker": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
+ },
+ "service_plans": {
+ "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
+ },
+ "service_broker": {
+ "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ {
+ "guid": "20e6cd62-12bb-11ea-90d1-7bfec2c75bcd",
+ "name": "other_service_offering",
+ "description": "Provides another service",
+ "available": true,
+ "tags": ["caching"],
+ "requires": [],
+ "created_at": "2019-11-29T16:44:02Z",
+ "updated_at": "2019-11-29T16:44:02Z",
+ "shareable": true,
+ "documentation_url": "https://some-other-documentation-link.io",
+ "broker_catalog": {
+ "id": "3cb11822-12bb-11ea-beb1-a350dc7453b9",
+ "metadata": {
+ "shareable": true
+ },
+ "features": {
+ "plan_updateable": true,
+ "bindable": true,
+ "instances_retrievable": true,
+ "bindings_retrievable": true,
+ "allow_context_updates": false
+ }
+ },
+ "relationships": {
+ "service_broker": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_offerings/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
+ },
+ "service_plans": {
+ "href": "https://api.example.org/v3/service_plans?service_offering_guids=20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
+ },
+ "service_broker": {
+ "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint retrieves the service offerings the user has access to.
+ +Definition
+ +GET /v3/service_offerings
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of names to filter by | +
| available | +boolean | +Filter by the available property; valid values are true or false |
+
| service_broker_guids | +list of strings | +Comma-delimited list of service broker GUIDs to filter by | +
| service_broker_names | +list of strings | +Comma-delimited list of service broker names to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space GUIDs to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization GUIDs to filter by | +
| label_selector | +string | +A query string containing a list of label selector requirements | +
| fields | +fields parameter | +Allowed values | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at, updated_at and name |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Service Offerings List Fields
+ +| Resource | +Allowed Keys | +
|---|---|
| service_broker | +guid, name |
+
Permitted roles
+ +| + |
|---|
| All Roles | +
Unauthenticated Users (for service offerings with public plans, unless hide_marketplace_from_unauthenticated_users is set) |
+
Update a service offering
+Example Request
+curl "https://api.example.org/v3/service_offerings/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "metadata": {
+ "labels": {"key": "value"},
+ "annotations": {"note": "detailed information"}
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_service_offering",
+ "description": "Provides my service",
+ "available": true,
+ "tags": ["relational", "caching"],
+ "requires": [],
+ "created_at": "2019-11-28T13:44:02Z",
+ "updated_at": "2019-11-28T13:44:02Z",
+ "shareable": true,
+ "documentation_url": "https://some-documentation-link.io",
+ "broker_catalog": {
+ "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
+ "metadata": {
+ "shareable": true
+ },
+ "features": {
+ "plan_updateable": true,
+ "bindable": true,
+ "instances_retrievable": true,
+ "bindings_retrievable": true,
+ "allow_context_updates": false
+ }
+ },
+ "relationships": {
+ "service_broker": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
+ },
+ "service_plans": {
+ "href": "https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a"
+ },
+ "service_broker": {
+ "href": "https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+}
+
+
+This endpoint updates a service offering with labels and annotations.
+ +Definition
+ +PATCH /v3/service_offerings/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the service offering | +
| metadata.annotations | +annotation object | +Annotations applied to the service offering | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | +Only for service offerings from space-scoped brokers | +
Delete a service offering
+Example Request
+curl "https://api.example.org/v3/service_offerings/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+This endpoint deletes a service offering. This is typically used to remove orphan service offerings from the Cloud +Foundry database when they have been removed from the service broker catalog, or when the service broker has been +removed.
+ +Note that this operation only affects the Cloud Foundry database, and no attempt is made to contact the service +broker.
+ +Definition
+ +DELETE /v3/service_offerings/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| purge | +boolean | +If true, any service plans, instances, and bindings associated with this service offering will also be deleted |
+
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | +Only service offerings from space-scoped brokers | +
Service Plans
+ +Service plans represent the service plans offered by a service offering. +A service offering will have one or more service plans. +Service offerings and service plans are created and updated when a service broker is registered or updated.
+The service plan object
+Example Service Plan object
+{
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_big_service_plan",
+ "description": "Big",
+ "visibility_type": "public",
+ "available": true,
+ "free": false,
+ "costs": [
+ {
+ "currency": "USD",
+ "amount": 199.99,
+ "unit": "Monthly"
+ }
+ ],
+ "created_at": "2019-11-28T13:44:02Z",
+ "updated_at": "2019-11-28T13:44:02Z",
+ "maintenance_info": {
+ "version": "1.0.0+dev4",
+ "description": "Database version 7.8.0"
+ },
+ "broker_catalog": {
+ "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
+ "metadata": {
+ "custom-key": "custom-information"
+ },
+ "maximum_polling_duration": null,
+ "features": {
+ "plan_updateable": true,
+ "bindable": true
+ }
+ },
+ "schemas": {
+ "service_instance": {
+ "create": {
+ "parameters": {
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "type": "object",
+ "properties": {
+ "billing-account": {
+ "description": "Billing account number used to charge use of shared fake server.",
+ "type": "string"
+ }
+ }
+ }
+ },
+ "update": {
+ "parameters": {}
+ }
+ },
+ "service_binding": {
+ "create": {
+ "parameters": {}
+ }
+ }
+ },
+ "relationships": {
+ "service_offering": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
+ },
+ "service_offering": {
+ "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ },
+ "visibility": {
+ "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
+ }
+ }
+}
+
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the service plan | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the service plan | +
| visibility_type | +string | +Denotes the visibility of the plan; can be public, admin, organization, space, see list of visibility types |
+
| available | +boolean | +Whether or not the service plan is available | +
| free | +boolean | +Whether or not the service plan is free of charge | +
| costs | +array of cost objects | +The cost of the service plan as obtained from the service broker catalog | +
| description | +string | +Description of the service plan | +
| maintenance_info | +maintenance_info object | +Information about the version of this service plan | +
| broker_catalog | +broker catalog object | +This object contains information obtained from the service broker catalog | +
| schemas | +schemas object | +Schema definitions for service instances and service bindings for the service plan | +
| relationships.service_offering | +to-one relationship | +The service offering that this service plan relates to | +
| relationships.space | +to-one relationship | +The space of the service broker, if this service plan is from a space-scoped service broker | +
| metadata.labels | +label object | +Labels applied to the service plan | +
| metadata.annotations | +annotation object | +Annotations added to the service plan | +
| links | +links object | +Links to related resources | +
The service plan cost
+ +| Name | +Type | +Description | +
|---|---|---|
| amount | +float | +Pricing amount | +
| currency | +string | +Currency code for the pricing amount, e.g. USD, GBP | +
| unit | +string | +Display name for type of cost, e.g. Monthly, Hourly, Request, GB | +
The maintenance info object for service plans
+ +| Name | +Type | +Description | +
|---|---|---|
| version | +string | +The current semantic version of the service plan; comparing this version with that of a service instance can be used to determine whether or not the service instance is up to date with this service plan | +
| description | +string | +A textual explanation associated with this version | +
The service plan broker catalog
+ +| Name | +Type | +Description | +
|---|---|---|
| id | +string | +The identifier that the service broker provided for this service plan | +
| metadata | +object | +Additional information provided by the service broker as specified by OSBAPI | +
| maximum_polling_duration | +integer | +The maximum number of seconds that Cloud Foundry will wait for an asynchronous service broker operation | +
| features.plan_updateable | +boolean | +Whether the service plan supports upgrade/downgrade for service plans; when the catalog does not specify a value, it is inherited from the service offering | +
| features.bindable | +boolean | +Specifies whether service instances of the service can be bound to applications | +
The service plan schemas
+ +| Name | +Type | +Description | +
|---|---|---|
| service_instance.create | +object | +Schema definition for service instance creation | +
| service_instance.create.parameters | +JSON Schema object | +The schema definition for the input parameters; each input parameter is expressed as a property within a JSON object | +
| service_instance.update | +object | +Schema definition for service instance update | +
| service_instance.update.parameters | +JSON Schema object | +The schema definition for the input parameters; each input parameter is expressed as a property within a JSON object | +
| service_binding.create | +object | +Schema definition for service Binding creation | +
| service_binding.create.parameters | +JSON Schema object | +The schema definition for the input parameters; each input parameter is expressed as a property within a JSON object | +
Get a service plan
+Example Request
+curl "https://api.example.org/v3/service_plans/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_big_service_plan",
+ "description": "Big",
+ "visibility_type": "public",
+ "available": true,
+ "free": false,
+ "costs": [
+ {
+ "currency": "USD",
+ "amount": 199.99,
+ "unit": "Monthly"
+ }
+ ],
+ "created_at": "2019-11-28T13:44:02Z",
+ "updated_at": "2019-11-28T13:44:02Z",
+ "maintenance_info": {
+ "version": "1.0.0+dev4",
+ "description": "Database version 7.8.0"
+ },
+ "broker_catalog": {
+ "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
+ "metadata": {
+ "custom-key": "custom-information"
+ },
+ "maximum_polling_duration": null,
+ "features": {
+ "plan_updateable": true,
+ "bindable": true
+ }
+ },
+ "schemas": {
+ "service_instance": {
+ "create": {
+ "parameters": {
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "type": "object",
+ "properties": {
+ "billing-account": {
+ "description": "Billing account number used to charge use of shared fake server.",
+ "type": "string"
+ }
+ }
+ }
+ },
+ "update": {
+ "parameters": {}
+ }
+ },
+ "service_binding": {
+ "create": {
+ "parameters": {}
+ }
+ }
+ },
+ "relationships": {
+ "service_offering": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
+ },
+ "service_offering": {
+ "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ },
+ "visibility": {
+ "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
+ }
+ }
+}
+
+
+This endpoint retrieves the service plan by GUID.
+ +Definition
+ +GET /v3/service_plans/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| fields | +fields parameter | +Allowed values | +
| include | +list of strings | +Optionally include a list of related resources in the response; valid values are space.organization and service_offering |
+
Service Plan Fields
+ +| Resource | +Allowed Keys | +
|---|---|
| service_offering.service_broker | +guid, name |
+
Permitted roles
+ +| + |
|---|
| All Roles | +
Unauthenticated Users (for public plans, unless hide_marketplace_from_unauthenticated_users is set) |
+
List service plans
+Example Request
+curl "https://api.example.org/v3/service_plans" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/service_plans?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/service_plans?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/service_plans?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_big_service_plan",
+ "description": "Big plan",
+ "visibility_type": "organization",
+ "available": true,
+ "free": false,
+ "costs": [
+ {
+ "currency": "USD",
+ "amount": 199.99,
+ "unit": "Monthly"
+ }
+ ],
+ "created_at": "2019-11-28T13:44:02Z",
+ "updated_at": "2019-11-28T13:44:02Z",
+ "maintenance_info": {
+ "version": "1.0.0+dev4",
+ "description": "Database version 7.8.0"
+ },
+ "broker_catalog": {
+ "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
+ "metadata": {
+ "custom-key": "custom-value"
+ },
+ "maximum_polling_duration": null,
+ "features": {
+ "plan_updateable": true,
+ "bindable": true
+ }
+ },
+ "schemas": {
+ "service_instance": {
+ "create": {
+ "parameters": {
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "type": "object",
+ "properties": {
+ "billing-account": {
+ "description": "Billing account number used to charge use of shared fake server.",
+ "type": "string"
+ }
+ }
+ }
+ },
+ "update": {
+ "parameters": {}
+ }
+ },
+ "service_binding": {
+ "create": {
+ "parameters": {}
+ }
+ }
+ },
+ "relationships": {
+ "service_offering": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
+ },
+ "service_offering": {
+ "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ },
+ "visibility": {
+ "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
+ }
+ }
+ },
+ {
+ "guid": "20e6cd62-12bb-11ea-90d1-7bfec2c75bcd",
+ "name": "other_service_plan",
+ "description": "Provides another service plan",
+ "visibility_type": "admin",
+ "available": true,
+ "free": true,
+ "created_at": "2019-11-29T16:44:02Z",
+ "updated_at": "2019-11-29T16:44:02Z",
+ "maintenance_info": {},
+ "broker_catalog": {
+ "id": "3cb11822-12bb-11ea-beb1-a350dc7453b9",
+ "metadata": {
+ "other-data": true
+ },
+ "maximum_polling_duration": null,
+ "features": {
+ "plan_updateable": true,
+ "bindable": true
+ }
+ },
+ "schemas": {
+ "service_instance": {
+ "create": {
+ "parameters": {}
+ },
+ "update": {
+ "parameters": {}
+ }
+ },
+ "service_binding": {
+ "create": {
+ "parameters": {}
+ }
+ }
+ },
+ "relationships": {
+ "service_offering": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_plans/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd"
+ },
+ "service_offering": {
+ "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ },
+ "visibility": {
+ "href": "https://api.example.org/v3/service_plans/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd/visibility"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint retrieves the service plans the user has access to.
+ +Definition
+ +GET /v3/service_plans
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of names to filter by | +
| available | +boolean | +Filter by the available property; valid values are true or false |
+
| broker_catalog_ids | +list of strings | +Comma-delimited list of IDs provided by the service broker for the service plan to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space GUIDs to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization GUIDs to filter by | +
| service_broker_guids | +list of strings | +Comma-delimited list of service broker GUIDs to filter by | +
| service_broker_names | +list of strings | +Comma-delimited list of service broker names to filter by | +
| service_offering_guids | +list of strings | +Comma-delimited list of service Offering GUIDs to filter by | +
| service_offering_names | +list of strings | +Comma-delimited list of service Offering names to filter by | +
| service_instance_guids | +list of strings | +Comma-delimited list of service Instance GUIDs to filter by | +
| include | +list of strings | +Optionally include a list of unique related resources in the response; valid values are space.organization and service_offering |
+
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at, name |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| fields | +fields parameter | +Allowed values | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
The organization_guids and space_guids filters do not filter plans that are public. +They both act on plans that are restricted to certain organizations, and to plans from space-scoped +service brokers.
+ +Service plans list fields
+ +| Resource | +Allowed keys | +
|---|---|
| service_offering.service_broker | +guid, name |
+
Permitted roles
+ +| + |
|---|
| All Roles | +
Unauthenticated Users (for public plans, unless hide_marketplace_from_unauthenticated_users is set) |
+
Update a service plan
+Example Request
+curl "https://api.example.org/v3/service_plans/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "metadata": {
+ "labels": {"key": "value"},
+ "annotations": {"note": "detailed information"}
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_big_service_plan",
+ "description": "Big",
+ "visibility_type": "public",
+ "available": true,
+ "free": false,
+ "costs": [
+ {
+ "currency": "USD",
+ "amount": 199.99,
+ "unit": "Monthly"
+ }
+ ],
+ "created_at": "2019-11-28T13:44:02Z",
+ "updated_at": "2019-11-28T13:44:02Z",
+ "maintenance_info": {
+ "version": "1.0.0+dev4",
+ "description": "Database version 7.8.0"
+ },
+ "broker_catalog": {
+ "id": "db730a8c-11e5-11ea-838a-0f4fff3b1cfb",
+ "metadata": {
+ "custom-key": "custom-information"
+ },
+ "maximum_polling_duration": null,
+ "features": {
+ "plan_updateable": true,
+ "bindable": true
+ }
+ },
+ "schemas": {
+ "service_instance": {
+ "create": {
+ "parameters": {
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "type": "object",
+ "properties": {
+ "billing-account": {
+ "description": "Billing account number used to charge use of shared fake server.",
+ "type": "string"
+ }
+ }
+ }
+ },
+ "update": {
+ "parameters": {}
+ }
+ },
+ "service_binding": {
+ "create": {
+ "parameters": {}
+ }
+ }
+ },
+ "relationships": {
+ "service_offering": {
+ "data": {
+ "guid": "13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9"
+ },
+ "service_offering": {
+ "href": "https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7"
+ },
+ "visibility": {
+ "href": "https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility"
+ }
+ }
+}
+
+
+This endpoint updates a service plan with labels and annotations.
+ +Definition
+ +PATCH /v3/service_plans/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the service plan | +
| metadata.annotations | +annotation object | +Annotations applied to the service plan | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | +Only for service plans from space-scoped brokers | +
Delete a service plan
+Example Request
+curl "https://api.example.org/v3/service_plans/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+This endpoint deletes a service plan. This is used to remove service plans from the Cloud Foundry database when they +are no longer provided by the service broker.
+ +Definition
+ +DELETE /v3/service_plans/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | +Only service plans from space-scoped brokers | +
Service Plan Visibility
+ +Service plan visibility is used to manage whether a role has access to a given service plan and its service offering.
+The service plan visibility object
+Example Service Plan Visibility object - organization restricted
+{
+ "type": "organization",
+ "organizations": [
+ {
+ "guid": "bf7eb420-11e5-11ea-b7db-4b5d5e7976a9",
+ "name": "my_org"
+ }
+ ]
+}
+
+Example Service Plan Visibility object - space restricted
+{
+ "type": "space",
+ "space": {
+ "guid": "ab7eb420-11e5-11ea-b7db-4b5d5e7975ad",
+ "name": "my_space"
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Denotes the visibility of the plan; can be public, admin, organization, space, see list of visibility types |
+
| space.guid | +string | +Unique identifier for the space whose members can access the plan; present if type is space |
+
| space.name | +string | +Name of the space whose members can access the plan; present if type is space |
+
| organizations | +array of organization object | +List of organizations whose members can access the plan; present if type is organization |
+
The organization visibility object
+ +| Name | +Type | +Description | +
|---|---|---|
| guid | +string | +Unique identifier for the organization where the plan is available | +
| name | +string | +Name of the organization where the plan is available | +
List of visibility types
+ +| Name | +Description | +
|---|---|
| public | +Everyone, including unauthenticated users can see the service plan | +
| admin | +Only Admin, Admin Read-Only and Global Auditor can see the service plan | +
| organization | +Restricted to members of a set of organizations | +
| space | +Restricted to members of a space; only possible if the plan comes from a space-scoped service broker | +
Get a service plan visibility
+Example Request
+curl "https://api.example.org/v3/service_plans/[guid]/visibility" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "type": "public"
+}
+
+This endpoint retrieves the service plan visibility for a given plan.
+ +Definition
+ +GET /v3/service_plans/:guid/visibility
Permitted roles
+ +| + |
|---|
| All Roles | +
Update a service plan visibility
+Example Request
+curl "https://api.example.org/v3/service_plans/[guid]/visibility" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "organization",
+ "organizations": [
+ { "guid" : "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482" }
+ ]
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "type": "organization",
+ "organizations": [
+ {
+ "guid": "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482",
+ "name": "other_org"
+ }
+ ]
+}
+
+This endpoint updates a service plan visibility. It behaves similar to the POST service plan visibility endpoint but this endpoint will replace the existing list of organizations when the service plan is organization visible.
Definition
+ +PATCH /v3/service_plans/:guid/visibility
Parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Denotes the visibility of the plan; can be public, admin, organization, see list of visibility types |
+
| organizations | +array of objects | +Desired list of organizations GUIDs where the plan will be accessible; required if type is organization |
+
Permitted roles
+ +| + |
|---|
| Admin | +
Apply a service plan visibility
+Example Request
+curl "https://api.example.org/v3/service_plans/[guid]/visibility" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "organization",
+ "organizations": [
+ { "guid": "0fc1ad4f-e1d7-4436-8e23-6b20f03c6482" }
+ ]
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "type": "organization"
+}
+
+This endpoint applies a service plan visibility. It behaves similar to the PATCH service plan visibility endpoint but this endpoint will append to the existing list of organizations when the service plan is organization visible.
Definition
+ +POST /v3/service_plans/:guid/visibility
Parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Denotes the visibility of the plan; can be public, admin, organization, see list of visibility types |
+
| organizations | +array of objects | +Desired list of organizations GUIDs where the plan will be accessible; required if type is organization |
+
Permitted roles
+ +| + |
|---|
| Admin | +
Remove organization from a service plan visibility
+Example Request
+curl "https://api.example.org/v3/service_plans/[guid]/visibility/[organization_guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+This endpoint removes an organization from a service plan visibility list of organizations. It is only defined for service plans which are org-restricted. It will fail with a HTTP status code of 422 for any other visibility type (e.g. Public).
+ +Definition
+ +DELETE /v3/service_plans/:guid/visibility/:organization_guid
Permitted roles
+ +| + |
|---|
| Admin | +
Service Instances
+ +An instantiation of a service.
+ +Service instances can be of type managed when it is an instantiation of a service offering registered with CF
+or user-provided when it describes an instance of an offering that is not registered with CF.
The service instance object
+Example Managed Service Instance object
+{
+ "guid": "c89b3280-fe8d-4aa0-a42e-44465bb1c61c",
+ "created_at": "2020-03-10T15:49:29Z",
+ "updated_at": "2020-03-10T15:49:29Z",
+ "name": "my-managed-instance",
+ "tags": [],
+ "type": "managed",
+ "maintenance_info": {
+ "version": "1.0.0"
+ },
+ "upgrade_available": false,
+ "dashboard_url": "https://service-broker.example.org/dashboard",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "relationships": {
+ "service_plan": {
+ "data": {
+ "guid": "5358d122-638e-11ea-afca-bf6e756684ac"
+ }
+ },
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ },
+ "service_plan": {
+ "href": "https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters"
+ },
+ "shared_spaces": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ }
+ }
+}
+
+Example User-Provided Service Instance object
+{
+ "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
+ "created_at": "2020-03-10T15:56:08Z",
+ "updated_at": "2020-03-10T15:56:08Z",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "name": "my-user-provided-instance",
+ "tags": ["sql"],
+ "type": "user-provided",
+ "syslog_drain_url": "http://logs.com",
+ "route_service_url": "https://routes.com",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "credentials": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the service instance | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the service instance | +
| type | +string | +Either managed or user-provided |
+
| tags | +list of strings | +Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env | +
| syslog_drain_url | +string | +URL to which logs for bound applications will be streamed; only shown when type is user-provided |
+
| route_service_url | +string | +URL to which requests for bound routes will be forwarded; only shown when type is user-provided |
+
| maintenance_info | +maintenance_info object | +Information about the version of this service instance; only shown when type is managed |
+
| upgrade_available | +bool | +Whether or not an upgrade of this service instance is available on the current Service Plan; details are available in the maintenance_info object; Only shown when type is managed |
+
| dashboard_url | +string | +The URL to the service instance dashboard (or null if there is none); only shown when type is managed |
+
| last_operation | +last operation object | +The last operation of this service instance | +
| relationships.service_plan | +to-one relationship | +The service plan the service instance relates to; only shown when type is managed |
+
| relationships.space | +to-one relationship | +The space the service instance is contained in | +
| metadata.labels | +label object | +Labels applied to the service instance | +
| metadata.annotations | +annotation object | +Annotations applied to the service instance | +
| links | +links object | +Links to related resources | +
The maintenance info object for service instances
+ +| Name | +Type | +Description | +
|---|---|---|
| version | +string | +The current semantic version of this service instance; comparing this version with the version of the Service Plan can be used to determine whether or not this service instance is up to date with the Service Plan | +
| description | +string | +A textual explanation associated with this version | +
The last operation object for service instances
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Either create, update, or delete |
+
| state | +string | +Either initial, in progress, succeeded, or failedNote: The initial state indicates that no response from the service broker has been received yet. |
+
| description | +string | +A textual explanation associated with this state | +
| created_at | +timestamp | +The time with zone when the operation started | +
| updated_at | +timestamp | +The time with zone when the operation was last updated | +
Create a service instance
+Example Request for Managed Service Instance
+curl "https://api.example.org/v3/service_instances" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "managed",
+ "name": "my_service_instance",
+ "parameters": {
+ "foo": "bar",
+ "baz": "qux"
+ },
+ "tags": ["foo", "bar", "baz"],
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
+ }
+ },
+ "service_plan": {
+ "data": {
+ "guid": "e0e4417c-74ee-11ea-a604-48bf6bec2d78"
+ }
+ }
+ }
+ }'
+Example Response for Managed Service Instance
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+Example Request for User-Provided Service Instance
+curl "https://api.example.org/v3/service_instances" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "user-provided",
+ "name": "my_service_instance",
+ "credentials": {
+ "foo": "bar",
+ "baz": "qux"
+ },
+ "tags": ["foo", "bar", "baz"],
+ "syslog_drain_url": "https://syslog.com/drain",
+ "route_service_url": "https://route.com/service",
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
+ }
+ }
+ }
+ }'
+Example Response for User-Provided Service Instance
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
+ "created_at": "2020-03-10T15:56:08Z",
+ "updated_at": "2020-03-10T15:56:08Z",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "name": "my-user-provided-instance",
+ "tags": ["sql"],
+ "type": "user-provided",
+ "syslog_drain_url": "http://logs.com",
+ "route_service_url": "https://routes.com",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {"baz":"qux"},
+ "annotations": {"foo":"bar"}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "credentials": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ }
+ }
+}
+
+This endpoint creates a new service instance. Service instances can be of type managed or user-provided, and
+the required parameters are different for each type. User provided service instances do not require interactions with
+service brokers.
If failures occur when creating managed service instances, the API might execute orphan mitigation steps +accordingly to cases outlined in the OSBAPI specification
+ +Definition
+ +POST /v3/service_instances
Required parameters for managed service instance
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Must be managed |
+
| name | +string | +Name of the service instance | +
| relationships.space | +to-one relationship | +The space in which to create the service instance | +
| relationships.service_plan | +to-one relationship | +The service plan from which to create the service instance | +
Optional parameters for managed service instance
+ +| Name | +Type | +Description | +
|---|---|---|
| tags | +list of strings | +Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env | +
| parameters | +object | +A JSON object that is passed to the service broker | +
| metadata.labels | +label object | +Labels applied to the service instance | +
| metadata.annotations | +annotation object | +Annotations applied to the service instance | +
Required parameters for user-provided service instance
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Must be user-provided |
+
| name | +string | +Name of the service instance | +
| relationships.space | +to-one relationship | +The space in which to create the service instance | +
Optional parameters for user-provided service instance
+ +| Name | +Type | +Description | +
|---|---|---|
| tags | +list of strings | +Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env | +
| credentials | +object | +A JSON object that is made available to apps bound to this service instance | +
| syslog_drain_url | +string | +URL to which logs for bound applications will be streamed | +
| route_service_url | +string | +URL to which requests for bound routes will be forwarded; must use the https protocol |
+
| metadata.labels | +label object | +Labels applied to the service instance | +
| metadata.annotations | +annotation object | +Annotations applied to the service instance | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Get a service instance
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Managed Service Instance Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "c89b3280-fe8d-4aa0-a42e-44465bb1c61c",
+ "created_at": "2020-03-10T15:49:29Z",
+ "updated_at": "2020-03-10T15:49:29Z",
+ "name": "my-managed-instance",
+ "tags": [],
+ "type": "managed",
+ "maintenance_info": {
+ "version": "1.0.0"
+ },
+ "upgrade_available": false,
+ "dashboard_url": "https://service-broker.example.org/dashboard",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "relationships": {
+ "service_plan": {
+ "data": {
+ "guid": "5358d122-638e-11ea-afca-bf6e756684ac"
+ }
+ },
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ },
+ "service_plan": {
+ "href": "https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters"
+ },
+ "shared_spaces": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ }
+ }
+}
+
+Example User-Provided Service Instance Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
+ "created_at": "2020-03-10T15:56:08Z",
+ "updated_at": "2020-03-10T15:56:08Z",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "name": "my-user-provided-instance",
+ "tags": ["sql"],
+ "type": "user-provided",
+ "syslog_drain_url": "http://logs.com",
+ "route_service_url": "https://routes.com",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "credentials": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ }
+ }
+}
+
+This endpoint retrieves the service instance by GUID.
+ +Definition
+ +GET /v3/service_instances/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| fields | +fields parameter | +Allowed values | +
Service Instance Fields
+ +| Resource | +Allowed Keys | +
|---|---|
| space | +guid, name |
+
| space.organization | +name, guid |
+
| service_plan | +name, guid |
+
| service_plan.service_offering | +name, guid, description, documentation_url, tags |
+
| service_plan.service_offering.service_broker | +name, guid |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List service instances
+Example Request
+curl "https://api.example.org/v3/service_instances" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/service_instances?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/service_instances?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "c89b3280-fe8d-4aa0-a42e-44465bb1c61c",
+ "created_at": "2020-03-10T15:49:29Z",
+ "updated_at": "2020-03-10T15:49:29Z",
+ "name": "my-managed-instance",
+ "tags": [],
+ "type": "managed",
+ "maintenance_info": {
+ "version": "1.0.0"
+ },
+ "upgrade_available": false,
+ "dashboard_url": "https://service-broker.example.org/dashboard",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "relationships": {
+ "service_plan": {
+ "data": {
+ "guid": "5358d122-638e-11ea-afca-bf6e756684ac"
+ }
+ },
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ },
+ "service_plan": {
+ "href": "https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters"
+ },
+ "shared_spaces": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ }
+ }
+ },
+ {
+ "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
+ "created_at": "2020-03-10T15:56:08Z",
+ "updated_at": "2020-03-10T15:56:08Z",
+ "name": "my-user-provided-instance",
+ "tags": ["sql"],
+ "type": "user-provided",
+ "syslog_drain_url": "http://logs.com",
+ "route_service_url": "https://routes.com",
+ "last_operation": {
+ "type": "update",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:59:32Z",
+ "created_at": "2020-03-10T15:59:29Z"
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "credentials": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint retrieves the service instances the user has access to, including access granted by service instance sharing.
+ +Definition
+ +GET /v3/service_instances
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of service instance names to filter by | +
| guids | +list of strings | +Comma-delimited list of service instance guids to filter by | +
| type | +string | +Filter by type; valid values are managed and user-provided |
+
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| service_plan_guids | +list of strings | +Comma-delimited list of service plan guids to filter by | +
| service_plan_names | +list of strings | +Comma-delimited list of service plan names to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at, updated_at, and name |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| fields | +fields parameter | +Allowed values | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Service Instances List Fields
+ +| Resource | +Allowed Keys | +
|---|---|
| space | +guid, name, relationships.organization |
+
| space.organization | +guid, name |
+
| service_plan | +guid, name, relationships.service_offering |
+
| service_plan.service_offering | +guid, name, description, documentation_url, tags, relationships.service_broker |
+
| service_plan.service_offering.service_broker | +guid, name |
+
Permitted roles
+ +| + |
|---|
| All Roles | +
Delete a service instance
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response for User-provided Service Instances
+HTTP/1.1 204 No Content
+Example Response for Managed Service Instance
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+This endpoint deletes a service instance and any associated service credential +bindings or service route bindings. The service instance is removed from all +spaces where it is available.
+ +User provided service instances do not require interactions with service brokers, +therefore the API will respond synchronously to the delete request.
+ +For managed service instances, the API will respond asynchronously. +If a service credential binding or service route binding cannot be deleted +synchronously, then the operation will fail, and the deletion of the binding +will continue in the background. The operation can be retried until it is successful.
+ +Definition
+ +DELETE /v3/service_instances/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| purge | +boolean | +If true, deletes the service instance and all associated resources without any interaction with the service broker. |
+
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | +Can only purge service instances from space-scoped brokers | +
Update a service instance
+Example Request for Managed Service Instance
+curl "https://api.example.org/v3/service_instances/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "my_service_instance",
+ "parameters": {
+ "foo": "bar",
+ "baz": "qux"
+ },
+ "tags": ["foo", "bar", "baz"],
+ "relationships": {
+ "service_plan": {
+ "data": {
+ "guid": "f2b6ba9c-a4d2-11ea-8ae6-48bf6bec2d78"
+ }
+ }
+ },
+ "metadata": {
+ "annotations": {
+ "note": "detailed information"
+ },
+ "labels": {
+ "key": "value"
+ }
+ }
+ }'
+Example Request for Managed Service Instance Upgrade (maintenance_info update)
+curl "https://api.example.org/v3/service_instances/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "maintenance_info": {
+ "version": "2.1.1"
+ }
+ }'
+Example Synchronous Response for Managed Service Instance:
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "c89b3280-fe8d-4aa0-a42e-44465bb1c61c",
+ "created_at": "2020-03-10T15:49:29Z",
+ "updated_at": "2020-03-10T15:49:29Z",
+ "name": "my-managed-instance",
+ "tags": [],
+ "type": "managed",
+ "maintenance_info": {
+ "version": "1.0.0"
+ },
+ "upgrade_available": false,
+ "dashboard_url": "https://service-broker.example.org/dashboard",
+ "last_operation": {
+ "type": "update",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "relationships": {
+ "service_plan": {
+ "data": {
+ "guid": "5358d122-638e-11ea-afca-bf6e756684ac"
+ }
+ },
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ },
+ "service_plan": {
+ "href": "https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters"
+ },
+ "shared_spaces": {
+ "href": "https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c"
+ }
+ }
+}
+
+Example Asynchronous Response for Managed Service Instance:
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+Example Request for User-Provided Service Instance
+curl "https://api.example.org/v3/service_instances/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my_service_instance",
+ "credentials": {
+ "foo": "bar",
+ "baz": "qux"
+ },
+ "tags": ["foo", "bar", "baz"],
+ "syslog_drain_url": "https://syslog.com/drain",
+ "route_service_url": "https://route.com/service",
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ }
+ }'
+Example Response for User-Provided Service Instance
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "88ce23e5-27c3-4381-a2df-32a28ec43133",
+ "created_at": "2020-03-10T15:56:08Z",
+ "updated_at": "2020-03-10T15:56:08Z",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "name": "my-user-provided-instance",
+ "tags": ["sql"],
+ "type": "user-provided",
+ "syslog_drain_url": "http://logs.com",
+ "route_service_url": "https://routes.com",
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ }
+ }
+ },
+ "metadata": {
+ "labels": {"baz":"qux"},
+ "annotations": {"foo":"bar"}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7"
+ },
+ "credentials": {
+ "href": "https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials"
+ },
+ "service_credential_bindings": {
+ "href": "https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ },
+ "service_route_bindings": {
+ "href": "https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/service_instances/:guid
Optional parameters for managed service instances
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the service instance | +
| tags | +list of strings | +Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env | +
| parameters | +object | +A JSON object that is passed to the service broker | +
| relationships.service_plan | +to-one relationship | +The service plan from which to create the service instance | +
| maintenance_info | +maintenance_info object | +If provided, must have the version field; version must be a semantic version value and it must match the version in the maintenance_info for the service instance plan in the updated broker catalog. Any other value for version will cause a MaintenanceInfoConflict error |
+
| metadata.labels | +label object | +Labels applied to the service_instance | +
| metadata.annotations | +annotation object | +Annotations applied to the service_instance | +
Some updates can be performed entirely within the Cloud Controller in which case the response is synchronous. +Some updates require communication with the service broker, in which case the response will be asynchronous. +The response will be asynchronous if any of these parameters are specified:
+ +-
+
parameters
+service_plan
+maintenance_info
+name- when the service offering hasallow_context_updatesfeature enabled
+
Otherwise the response will be synchronous.
+ +Optional parameters for user-provided service instances
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the service instance | +
| tags | +list of strings | +Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env | +
| credentials | +object | +A JSON object that is made available to apps bound to this service instance | +
| syslog_drain_url | +string | +URL to which logs for bound applications will be streamed | +
| route_service_url | +string | +URL to which requests for bound routes will be forwarded; must use the https protocol |
+
| metadata.labels | +label object | +Labels applied to the service_instance | +
| metadata.annotations | +annotation object | +Annotations applied to the service_instance | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Get credentials for a user-provided service instance
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]/credentials" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "username": "my-username",
+ "password": "super-secret",
+ "other": "credential"
+}
+
+Retrieves the credentials for a user-provided service instance. +This endpoint is not available for managed service instances.
+ +Definition
+ +GET /v3/service_instances/:guid/credentials
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Space Developer | +
| Space Manager | +
Get usage summary in shared spaces
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces/usage_summary" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "usage_summary": [
+ {
+ "space": {
+ "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
+ },
+ "bound_app_count": 2
+ },
+ {
+ "space": {
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ },
+ "bound_app_count": 0
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces/usage_summary"
+ },
+ "shared_spaces": {
+ "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c"
+ }
+ }
+}
+
+This endpoint returns the number of bound apps in spaces where the service instance has been shared to.
+ +Definition
+ +GET /v3/service_instances/:guid/relationships/shared_spaces/usage_summary
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List shared spaces relationship
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ {
+ "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
+ },
+ {
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
+ }
+ }
+}
+
+This endpoint lists the spaces that the service instance has been shared to.
+ +Definition
+ +GET /v3/service_instances/:guid/relationships/shared_spaces
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| fields | +fields parameter | +Allowed values | +
Shared Spaces List Fields
+ +| Resource | +Allowed Keys | +
|---|---|
| space | +guid, name, relationships.organization |
+
| space.organization | +guid, name |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Get parameters for a managed service instance
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]/parameters" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "key_1": "value_1",
+ "key_2": "value_2"
+}
+
+Queries the Service Broker for the parameters associated with this service instance.
+The broker catalog must have enabled the instances_retrievable feature for the Service Offering.
+Check the Service Offering object for the value of this feature flag.
Definition
+ +GET /v3/service_instances/:guid/parameters
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
Get permissions for a service instance
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]/permissions" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "read": true,
+ "manage": false
+}
+
+Get the current user’s permissions for the given service instance. If a user can get a service instance then they can ‘read’ it. Users who can update a service instance can ‘manage’ it.
+ +This endpoint’s primary purpose is to enable third-party service dashboards to determine the permissions of a given Cloud Foundry user that has authenticated with the dashboard via single sign-on (SSO). For more information, see the Cloud Foundry documentation on Dashboard Single Sign-On.
+ +Definition
+ +GET /v3/service_instances/:guid/permissions
Permitted roles
+ +| + |
|---|
| All Roles | +
Share a service instance to other spaces
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "data": [
+ { "guid":"space-guid-1" },
+ { "guid":"space-guid-2" }
+ ]
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": [
+ {
+ "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
+ },
+ {
+ "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+ }
+ ],
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
+ }
+ }
+}
+
+This endpoint shares the service instance with the specified spaces. +In order to share into a space the requesting user must be a space developer in the target space.
+ +Definition
+ +POST /v3/service_instances/:guid/relationships/shared_spaces
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-many relationship | +Shared space relationships; each space will have this service instance shared to it | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Unshare a service instance from another space
+Example Request
+curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces/[space_guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+This endpoint unshares the service instance from the specified space. This will automatically unbind any applications bound to this service instance in the specified space. +Unsharing a service instance from a space will not delete any service keys.
+ +Definition
+ +DELETE /v3/service_instances/:guid/relationships/shared_spaces/:space_guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Service Credential Binding
+ +Service credential bindings are used to make the details of the connection to a service instance available to an app or a developer.
+ +Service credential bindings can be of type app or key.
A service credential binding is of type app when it is a binding between a service instance and an application
+Not all services support this binding, as some services deliver value to users directly without integration with an application.
+Field broker_catalog.features.bindable from service plan of the service instance can be used to determine if it is bindable.
A service credential binding is of type key when it only retrieves the details of the service instance and makes them available to the developer.
The service credential binding object
+Example App Service Credential Binding object
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "name": "some-name",
+ "type": "app",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "service_instance": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "details": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ }
+}
+
+Example Key Service Credential Binding object
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "name": "some-name",
+ "type": "key",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "details": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the service credential binding | +
| name | +string | +Name of the binding. null when it’s not defined. |
+
| type | +string | +Either app or key |
+
| last_operation | +last operation object | +The last operation of this binding | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| metadata.labels | +label object | +Labels applied to the service credential binding | +
| metadata.annotations | +annotation object | +Annotations applied to the service credential binding | +
| relationships.service_instance | +to-one relationship | +The service instance that this binding is originated from | +
| relationships.app | +to-one relationship | +The app using this binding; omitted for key bindings |
+
| links | +links object | +Links to related resources | +
The last operation object for service credential binding
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Either create or delete |
+
| state | +string | +Either initial, in progress, succeeded, or failedNote: The initial state indicates that no response from the service broker has been received yet. |
+
| description | +string | +A textual explanation associated with this state | +
| created_at | +timestamp | +The time with zone when the operation started | +
| updated_at | +timestamp | +The time with zone when the operation was last updated | +
Create a service credential binding
+Example Request to create an App Credential Binding
+curl "https://api.example.org/v3/service_credential_bindings" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "app",
+ "name": "some-binding-name",
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
+ }
+ },
+ "app": {
+ "data": {
+ "guid": "e0e4417c-74ee-11ea-a604-48bf6bec2d78"
+ }
+ }
+ },
+ "parameters": {
+ "key1": "value1",
+ "key2": "value2"
+ },
+ "metadata": {
+ "labels": {
+ "foo": "bar"
+ },
+ "annotations": {
+ "baz": "qux"
+ }
+ }
+ }'
+Example Request to create a Key Credential Binding
+curl "https://api.example.org/v3/service_credential_bindings" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "type": "key",
+ "name": "some-binding-name",
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
+ }
+ }
+ },
+ "parameters": {
+ "key1": "value1",
+ "key2": "value2"
+ },
+ "metadata": {
+ "labels": {
+ "foo": "bar"
+ },
+ "annotations": {
+ "baz": "qux"
+ }
+ }
+ }'
+Example Response for a Managed Service Instance
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+Example Response for a User-Provided Service Instance
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "name": "some-name",
+ "type": "app",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "service_instance": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "details": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ }
+}
+
+This endpoint creates a new service credential binding. Service credential bindings can be of type app or key; key is only
+valid for managed service instances.
If failures occur when creating a service credential binding for a managed service instances, the API might execute orphan mitigation steps +accordingly to cases outlined in the OSBAPI specification
+ +Definition
+ +POST /v3/service_credential_bindings
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| type | +string | +Type of the service credential binding. Valid values are key and app |
+
| relationships.service_instance | +to-one relationship | +The service instance to be bound | +
| name | +string | +Name of the service credential binding. name is optional when the type is app |
+
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| relationships.app | +to-one relationship | +The app to be bound. Required when type is app |
+
| parameters | +object | +A JSON object that is passed to the service broker | +
| metadata.labels | +label object | +Labels applied to the service credential binding | +
| metadata.annotations | +annotation object | +Annotations applied to the service credential binding | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | ++ |
| Space Supporter | +Only allowed to create bindings of type app. |
+
Get a service credential binding
+Example Request
+curl "https://api.example.org/v3/service_credential_bindings/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example App Credential Binding Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "name": "some-name",
+ "type": "app",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "service_instance": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "details": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ }
+}
+
+Example Key Credential Binding Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "name": "some-name",
+ "type": "key",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "details": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+}
+
+This endpoint retrieves the service credential binding by GUID.
+ +Definition
+ +GET /v3/service_credential_bindings/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| include | +list of strings | +Optionally include a list of unique related resources in the response. Valid values are: app, service_instance |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List service credential bindings
+Example Request
+curl "https://api.example.org/v3/service_credential_bindings \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/service_credential_bindings?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/service_credential_bindings?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/service_credential_bindings?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "name": "some-binding-name",
+ "type": "app",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "service_instance": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "details": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ }
+ },
+ {
+ "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "name": "some-key-name",
+ "type": "key",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": { }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_credential_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
+ },
+ "details": {
+ "href": "https://api.example.org/v3/service_credential_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62/details"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bf356j3-9e18-45b1-3333-124163f31f9e"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint retrieves the service credential bindings the user has access to.
+ +Definition
+ +GET /v3/service_credential_bindings
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of service credential binding names to filter by | +
| service_instance_guids | +list of strings | +Comma-delimited list of service instance guids to filter by | +
| service_instance_names | +list of strings | +Comma-delimited list of service instance names to filter by | +
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| app_names | +strings | +Comma-delimited list of app names to filter by | +
| service_plan_guids | +list of strings | +Comma-delimited list of service plan guids to filter by | +
| service_plan_names | +list of strings | +Comma-delimited list of service plan names to filter by | +
| service_offering_guids | +list of strings | +Comma-delimited list of service offering guids to filter by | +
| service_offering_names | +list of strings | +Comma-delimited list of service offering names to filter by | +
| type | +list of strings | +Type of credential binding to filter by. Valid values are: app or key |
+
| guids | +list of strings | +Comma-delimited list of service route binding guids to filter by | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| include | +list of strings | +Optionally include a list of unique related resources in the response. Valid values are: app, service_instance |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at, updated_at, and name |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update a service credential binding
+Example Request
+curl "https://api.example.org/v3/service_credential_bindings/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "metadata": {
+ "labels": {"foo": "bar"},
+ "annotations": {"baz": "qux"}
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "name": "some-name",
+ "type": "app",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "service_instance": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "details": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ }
+}
+
+This endpoint updates a service credential binding with labels and annotations.
+ +Definition
+ +PATCH /v3/service_credential_bindings/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the service credential binding | +
| metadata.annotations | +annotation object | +Annotations applied to the service credential binding | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Delete a service credential binding
+Example Request
+curl "https://api.example.org/v3/service_credential_bindings/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response for User-provided Service Instances
+HTTP/1.1 204 No Content
+Example Response for Managed Service Instance
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+This endpoint deletes a service credential binding. When deleting credential bindings originated from user provided +service instances, the delete operation does not require interactions with service brokers, therefore the API will +respond synchronously to the delete request.
+ +Definition
+ +DELETE /v3/service_credential_bindings/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Space Developer | ++ |
| Space Supporter | +Only allowed to delete bindings of type app. |
+
Get a service credential binding details
+Example Request
+curl "https://api.example.org/v3/service_credential_bindings/[guid]/details" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Credential Binding Details Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "credentials": {
+ "connection": "mydb://user@password:example.com"
+ },
+ "syslog_drain_url": "http://syslog.example.com/drain",
+ "volume_mounts": ["/vcap/data", "store"]
+}
+
+This endpoint retrieves the service credential binding details.
+ +Definition
+ +GET /v3/service_credential_bindings/:guid/details
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Space Developer | +
Get parameters for a service credential binding
+Example Request
+curl "https://api.example.org/v3/service_credential_bindings/[guid]/parameters" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "foo": "bar",
+ "foz": "baz"
+}
+Queries the Service Broker for the parameters associated with this service credential binding.
+The broker catalog must have enabled the bindings_retrievable feature for the Service Offering.
+Check the Service Offering object for the value of this feature flag.
+This endpoint is not available for User-Provided Service Instances.
Definition
+ +GET /v3/service_credential_bindings/:guid/parameters
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Space Developer | +
| Space Supporter | +
Service Route Binding
+ +Service route bindings are relations between a service instance and a route.
+ +Not all service instances support route binding.
+In order to bind to a managed service instance, the service instance should be created from a service offering that has requires route forwarding (requires=[route_forwarding]).
+In order to bind to a user-provided service instance, the service instance must have route_service_url set.
The service route binding object
+Example Service Route Binding object
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "route_service_url": "https://route-service-url.io",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "route": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the service route binding | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| route_service_url | +string | +The URL for the route service | +
| metadata.labels | +label object | +Labels applied to the service route binding | +
| metadata.annotations | +annotation object | +Annotations applied to the service route binding | +
| relationships.service_instance | +to-one relationship | +The service instance that the route is bound to | +
| relationships.route | +to-one relationship | +The route that the service instance is bound to | +
| links | +links object | +Links to related resources | +
Get a service route binding
+Example Request
+curl "https://api.example.org/v3/service_route_bindings/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "route_service_url": "https://route-service-url.io",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "route": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
+ }
+ }
+}
+
+This endpoint retrieves the service route binding by GUID.
+ +Definition
+ +GET /v3/service_route_bindings/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| include | +list of strings | +Optionally include a list of unique related resources in the response. Valid values are: route, service_instance |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List service route bindings
+Example Request
+curl "https://api.example.org/v3/service_route_bindings \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/service_route_bindings?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/service_route_bindings?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/service_route_bindings?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "4ac1a475-0f4d-4e4b-8ff6-957c94f68211",
+ "route_service_url": "https://some-route-1.api.example.org",
+ "created_at": "2020-09-08T08:55:59Z",
+ "updated_at": "2020-09-08T08:55:59Z",
+ "last_operation": null,
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "39903ed2-6476-4c78-843a-0195f5fc4ccd"
+ }
+ },
+ "route": {
+ "data": {
+ "guid": "15697508-cb68-4d88-9f19-85fc53851571"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_route_bindings/4ac1a475-0f4d-4e4b-8ff6-957c94f68211"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/39903ed2-6476-4c78-843a-0195f5fc4ccd"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/15697508-cb68-4d88-9f19-85fc53851571"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
+ }
+ }
+ },
+ {
+ "guid": "bdf63c4f-85af-4c20-bea9-e9def7d57dab",
+ "route_service_url": "https://some-route-2.api.example.org",
+ "created_at": "2020-09-08T09:13:51Z",
+ "updated_at": "2020-09-08T09:13:51Z",
+ "last_operation": null,
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "f957dc7c-46d1-4a3f-973d-71ce5fdec788"
+ }
+ },
+ "route": {
+ "data": {
+ "guid": "75ebe2a1-04b0-407b-b33c-733388fc7aa4"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_route_bindings/bdf63c4f-85af-4c20-bea9-e9def7d57dab"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/f957dc7c-46d1-4a3f-973d-71ce5fdec788"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/75ebe2a1-04b0-407b-b33c-733388fc7aa4"
+ }
+ }
+ }
+ ]
+ }
+
+This endpoint retrieves the service route bindings the user has access to.
+ +Definition
+ +GET /v3/service_route_bindings
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| route_guids | +list of strings | +Comma-delimited list of route guids to filter by | +
| service_instance_guids | +list of strings | +Comma-delimited list of service instance guids to filter by | +
| service_instance_names | +list of strings | +Comma-delimited list of service instance names to filter by | +
| label_selector | +string | +A query string containing a list of label selector requirements | +
| guids | +list of strings | +Comma-delimited list of service route binding guids to filter by | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| include | +list of strings | +Optionally include a list of unique related resources in the response. Valid values are: route, service_instance |
+
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at, updated_at |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Create a service route binding
+Example Request
+curl "https://api.example.org/v3/service_route_bindings" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "route": {
+ "data": {
+ "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
+ }
+ },
+ "service_instance": {
+ "data": {
+ "guid": "e0e4417c-74ee-11ea-a604-48bf6bec2d78"
+ }
+ }
+ },
+ "parameters": {
+ "key1": "value1",
+ "key2": "value2"
+ }
+ }'
+Example Response for Managed Service Instance
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+Example Response for User-Provided Service Instance
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "route_service_url": "https://route-service-url.io",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "route": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
+ }
+ }
+}
+
+This endpoint creates a new route service binding. The service instance and the route +must be in the same space.
+ +To bind a route to a user-provided service instance, the service instance must
+have the route_service_url property set.
To bind a route to a managed service instance, the service offering must be bindable,
+and the service offering must have route_forwarding set in the requires property.
Definition
+ +POST /v3/service_route_bindings
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| relationships.route | +to-one relationship | +The route to bind | +
| relationships.service_instance | +to-one relationship | +The service instance to bind | +
Optional parameters for managed service instances
+ +| Name | +Type | +Description | +
|---|---|---|
| parameters | +object | +A JSON object that is passed to the service broker | +
| metadata.labels | +label object | +Labels applied to the service route binding | +
| metadata.annotations | +annotation object | +Annotations applied to the service route binding | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Update a service route binding
+Example Request
+curl "https://api.example.org/v3/service_route_bindings/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "metadata": {
+ "labels": {"key": "value"},
+ "annotations": {"note": "detailed information"}
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
+ "created_at": "2015-11-13T17:02:56Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "route_service_url": "https://route-service-url.io",
+ "last_operation": {
+ "type": "create",
+ "state": "succeeded",
+ "description": "Operation succeeded",
+ "updated_at": "2020-03-10T15:49:32Z",
+ "created_at": "2020-03-10T15:49:29Z"
+ },
+ "metadata": {
+ "annotations": {
+ "foo": "bar"
+ },
+ "labels": {
+ "baz": "qux"
+ }
+ },
+ "relationships": {
+ "service_instance": {
+ "data": {
+ "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
+ }
+ },
+ "route": {
+ "data": {
+ "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
+ },
+ "service_instance": {
+ "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
+ },
+ "route": {
+ "href": "https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13"
+ },
+ "parameters": {
+ "href": "https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters"
+ }
+ }
+}
+
+This endpoint updates a service route binding with labels and annotations.
+ +Definition
+ +PATCH /v3/service_route_bindings/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the service route binding | +
| metadata.annotations | +annotation object | +Annotations applied to the service route binding | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Delete a service route binding
+Example Request
+curl "https://api.example.org/v3/service_route_bindings/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response for User-provided Service Instances
+HTTP/1.1 204 No Content
+Example Response for Managed Service Instance
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788
+This endpoint deletes a service route binding. When deleting route bindings originating from user provided +service instances, the delete operation does not require interactions with service brokers, therefore the API will +respond synchronously to the delete request. Consequently, deleting route bindings from managed service instances +responds with a job which can be used to track the progress of the delete operation.
+ +Definition
+ +DELETE /v3/service_route_bindings/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Get parameters for a route binding
+Example Request
+curl "https://api.example.org/v3/service_route_bindings/[guid]/parameters" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "foo": "bar",
+ "foz": "baz"
+}
+Queries the Service Broker for the parameters associated with this service route binding.
+The broker catalog must have enabled the bindings_retrievable feature for the Service Offering.
+Check the Service Offering object for the value of this feature flag.
+This endpoint is not available for User-Provided Service Instances.
Definition
+ +GET /v3/service_route_bindings/:guid/parameters
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Space Developer | +
Service Usage Events
+ +Service usage events are a record of changes in the usage of services. For +example, service usage events are recorded when a service instance is created, +updated, and deleted. They may contain information about the service instance in +question and the associated space, service broker, and service offering.
+ +Usage events are typically used by billing and chargeback applications.
+The service usage event object
+Example Service Usage Event object
+{
+ "guid": "c9976002-96f4-435a-888e-db1e1178df62",
+ "created_at": "2020-05-28T12:34:56Z",
+ "updated_at": "2020-05-28T12:34:56Z",
+ "state": "CREATED",
+ "space": {
+ "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
+ "name": "name-1664"
+ },
+ "organization": {
+ "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
+ },
+ "service_instance": {
+ "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
+ "name": "name-1982",
+ "type": "managed_service_instance"
+ },
+ "service_plan": {
+ "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
+ "name": "name-1983"
+ },
+ "service_offering": {
+ "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
+ "name": "label-64"
+ },
+ "service_broker": {
+ "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
+ "name": "name-2929"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_usage_events/c9976002-96f4-435a-888e-db1e1178df62"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the event | +
| created_at | +timestamp | +The time with zone when the event occurred | +
| updated_at | +timestamp | +Identical to created_at (events are created, never updated) |
+
| state | +string or null |
+Current state of the service that this event pertains to, if applicable | +
| space.guid | +string or null |
+Unique identifier of the space that this event pertains to, if applicable | +
| space.name | +string or null |
+Name of the space that this event pertains to, if applicable | +
| organization.guid | +string or null |
+Unique identifier of the org that this event pertains to, if applicable | +
| service_instance.guid | +string or null |
+Unique identifier of the service instance that this event pertains to, if applicable | +
| service_instance.name | +string or null |
+Name of the service instance that this event pertains to, if applicable | +
| service_instance.type | +string or null |
+Type of the service instance that this event pertains to, if applicable | +
| service_plan.guid | +string or null |
+Unique identifier of the service plan that this event pertains to, if applicable | +
| service_plan.name | +string or null |
+Name of the service plan that this event pertains to, if applicable | +
| service_offering.guid | +string or null |
+Unique identifier of the service offering that this event pertains to, if applicable | +
| service_offering.name | +string or null |
+Name of the service offering that this event pertains to, if applicable | +
| service_broker.guid | +string or null |
+Unique identifier of the service broker that this event pertains to, if applicable | +
| service_broker.name | +string or null |
+Name of the service broker that this event pertains to, if applicable | +
| links | +links object | +Links to related resources | +
Get a service usage event
+Example Request
+curl "https://api.example.org/v3/service_usage_events/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "c9976002-96f4-435a-888e-db1e1178df62",
+ "created_at": "2020-05-28T12:34:56Z",
+ "updated_at": "2020-05-28T12:34:56Z",
+ "state": "CREATED",
+ "space": {
+ "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
+ "name": "name-1664"
+ },
+ "organization": {
+ "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
+ },
+ "service_instance": {
+ "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
+ "name": "name-1982",
+ "type": "managed_service_instance"
+ },
+ "service_plan": {
+ "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
+ "name": "name-1983"
+ },
+ "service_offering": {
+ "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
+ "name": "label-64"
+ },
+ "service_broker": {
+ "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
+ "name": "name-2929"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_usage_events/c9976002-96f4-435a-888e-db1e1178df62"
+ }
+ }
+}
+
+Retrieve a service usage event.
+ +Definition
+ +GET /v3/service_usage_events/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
List service usage events
+Example Request
+curl "https://api.example.org/v3/service_usage_events" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/service_usage_events?page=1&per_page=1"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/service_usage_events?page=2&per_page=1"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/service_usage_events?page=2&per_page=1"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "c9976002-96f4-435a-888e-db1e1178df62",
+ "created_at": "2020-05-28T12:34:56Z",
+ "updated_at": "2020-05-28T12:34:56Z",
+ "state": "CREATED",
+ "space": {
+ "guid": "guid-5e28f12f-9d80-473e-b826-537b148eb338",
+ "name": "name-1664"
+ },
+ "organization": {
+ "guid": "guid-036444f4-f2f5-4ea8-a353-e73330ca0f0a"
+ },
+ "service_instance": {
+ "guid": "guid-f93250f7-7ef5-4b02-8d33-353919ce8358",
+ "name": "name-1982",
+ "type": "managed_service_instance"
+ },
+ "service_plan": {
+ "guid": "guid-e9d2d5a0-69a6-46ef-bac5-43f3ed177614",
+ "name": "name-1983"
+ },
+ "service_offering": {
+ "guid": "guid-34916716-31d7-40c1-9afd-f312996c9654",
+ "name": "label-64"
+ },
+ "service_broker": {
+ "guid": "guid-7cc11646-bf38-4f4e-b6e0-9581916a74d9",
+ "name": "name-2929"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/service_usage_events/c9976002-96f4-435a-888e-db1e1178df62"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all service usage events the user has access to.
+ +Definition
+ +GET /v3/service_usage_events
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending; valid value is created_at |
+
| after_guid | +string | +Filters out events before and including the event with the given guid | +
| guids | +list of strings | +Comma-delimited list of usage event guids to filter by | +
| service_instance_types | +list of strings | +Comma-delimited list of service instance types to filter by; valid values are managed_service_instance and user_provided_service_instance |
+
| service_offering_guids | +list of strings | +Comma-delimited list of service offering guids to filter by | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Purge and seed service usage events
+Example Request
+curl "https://api.example.org/v3/service_usage_events/actions/destructively_purge_all_and_reseed" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+Destroys all existing events. Populates new usage events, one for each existing service instance. All populated events will have a created_at value of current time. There is the potential race condition if service instances are currently being created or deleted. The seeded usage events will have the same guid as the service instance.
Definition
+ +POST /v3/service_usage_events/actions/destructively_purge_all_and_reseed
Permitted roles
+ +| + |
|---|
| Admin | +
Sidecars
+ +Sidecars are additional operating system processes that are run in the same container as a process.
+ +Use cases for sidecars
+ +Sidecars are useful for any app processes that need to communicate with another within the same container or are otherwise dependent on each other. Some use cases are:
+ +-
+
- Two or more processes that require access to a shared file +
- An Application Performance Monitoring (APM) tool that attaches to a dependent app’s processes +
- Two or more processes that communicate via a local socket +
Steps to create a sidecar
+ +The recommended way to create sidecars for your app is with a manifest.
+ sidecars:
+ - name: authenticator
+ process_types: [ 'web', 'worker' ]
+ command: bundle exec run-authenticator
+ - name: performance monitor
+ process_types: [ 'web' ]
+ command: bundle exec run-performance-monitor
+ memory: 128M
+-
+
- name is a user defined identifier (unique per app) +
- process_types is a list of app processes the sidecar will attach to. You can attach multiple sidecars to each process type your app uses +
- command is the command used to start the sidecar +
- memory is the memory reserved for the sidecar[1] +
1 Applies for Java apps. If you do not reserve memory for the sidecar, the JVM will consume all of the memory in the app container. This value must be less thatn the process’ reserved memory.
+ +Current limitations
+ +-
+
- Start and stop order of app processes and their sidecars is undefined +
- App processes and sidecar processes are codependent: if either crashes or exits, the other will as well +
- Sidecars are currently not independently scalable (memory / disk) and share resources with the main app process and other sidecars within that container +
- Sidecars only support PID based health checks; HTTP health-checks for sidecars are not currently supported +
- This has only been tested on Linux based systems +
The sidecar object
+Example Sidecar object
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300,
+ "origin": "user",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z"
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the sidecar | +
| name | +string | +Human-readable name for the sidecar | +
| command | +string | +The command used to start the sidecar | +
| process_types | +list of strings | +A list of process types the sidecar applies to | +
| memory_in_mb | +integer | +Reserved memory for sidecar | +
| origin | +string | +Specifies whether the sidecar was created by the user or via the buildpack | +
| relationships.app | +to-one relationship | +The app the sidecar is associated with | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
Create a sidecar associated with an app
+Example Request
+curl "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/sidecars" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300,
+ "origin": "user",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z"
+}
+
+Definition
+ +POST /v3/apps/:guid/sidecars
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Human-readable name for the sidecar | +
| command | +string | +The command used to start the sidecar | +
| process_types | +list of strings | +A list of process types the sidecar applies to | +
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| memory_in_mb | +integer | +Reserved memory for sidecar | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Get a sidecar
+Example Request
+curl "https://api.example.org/v3/sidecars/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300,
+ "origin": "user",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z"
+}
+
+Definition
+ +GET /v3/sidecars/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update a sidecar
+Example Request
+curl "https://api.example.org/v3/sidecars/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300
+ }'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300,
+ "origin": "user",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z"
+}
+
+Definition
+ +PATCH /v3/sidecars/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Human-readable name for the sidecar | +
| command | +string | +The command used to start the sidecar | +
| process_types | +list of strings | +A list of process types the sidecar applies to | +
| memory_in_mb | +integer | +Reserved memory for sidecar | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
List sidecars for app
+Example Request
+curl "https://api.example.org/v3/apps/[guid]/sidecars" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300,
+ "origin": "user",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z"
+ },
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
+ "name": "echo-sidecar",
+ "command": "start-echo-server",
+ "process_types": ["web"],
+ "memory_in_mb": 300,
+ "origin": "user",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:59Z",
+ "updated_at": "2017-02-01T01:33:59Z"
+ }
+ ]
+}
+
+Retrieves all sidecars associated with a app.
+ +Definition
+ +GET /v3/apps/:guid/sidecars
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List sidecars for process
+Example Request
+curl "https://api.example.org/v3/processes/[guid]/sidecars" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "name": "auth-sidecar",
+ "command": "bundle exec rackup",
+ "process_types": ["web", "worker"],
+ "memory_in_mb": 300,
+ "origin": "user",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z"
+ },
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
+ "name": "echo-sidecar",
+ "command": "start-echo-server",
+ "process_types": ["web"],
+ "memory_in_mb": 300,
+ "origin": "user",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
+ }
+ }
+ },
+ "created_at": "2017-02-01T01:33:59Z",
+ "updated_at": "2017-02-01T01:33:59Z"
+ }
+ ]
+}
+
+Retrieves all sidecars associated with a process.
+ +Definition
+ +GET /v3/processes/:guid/sidecars
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Delete a sidecar
+Example Request
+curl "https://api.example.org/v3/sidecars/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+Definition
+ +DELETE /v3/sidecars/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Spaces
+ +Every application and service is scoped to a space. Each org contains at least one space. A space provides users with access to a shared location for application development, deployment, and maintenance.
+The space object
+Example Space object
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "my-space",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
+ }
+ },
+ "quota": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
+ },
+ "apply_manifest": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
+ "method": "POST"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the space | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +Name of the space | +
| relationships.organization | +to-one relationship | +The organization the space is contained in | +
| relationships.quota | +to-one relationship | +The space quota applied to the space | +
| metadata.labels | +label object | +Labels applied to the space | +
| metadata.annotations | +annotation object | +Annotations applied to the space | +
| links | +links object | +Links to related resources | +
Create a space
+Example Request
+curl "https://api.example.org/v3/spaces" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "my-space",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "[org-guid]"
+ }
+ }
+ }
+ }'
+
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "my-space",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
+ }
+ },
+ "quota": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
+ },
+ "apply_manifest": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
+ "method": "POST"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +POST /v3/spaces
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Space name | +
| relationships.organization | +to-one relationship | +A relationship to an organization | +
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the space | +
| metadata.annotations | +annotation object | +Annotations applied to the space | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Org Manager | +
Get a space
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "my-space",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
+ }
+ },
+ "quota": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
+ },
+ "apply_manifest": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
+ "method": "POST"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+This endpoint retrieves the specified space object.
+ +Definition
+ +GET /v3/spaces/:guid
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| include | +list of strings | +Optionally include additional related resources in the response; valid value is organization |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List spaces
+Example Request
+curl "https://api.example.org/v3/spaces" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/spaces?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/spaces?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "space1",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
+ }
+ },
+ "quota": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
+ },
+ "apply_manifest": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
+ "method": "POST"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
+ "created_at": "2017-02-02T00:14:30Z",
+ "updated_at": "2017-02-02T00:14:30Z",
+ "name": "space2",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "b4ce91bd-31df-4b7d-8fd4-21a6b533276b"
+ }
+ },
+ "quota": {
+ "data": {
+ "guid": "6da62599-4890-4a08-8b6f-180a4f47e46b"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/features"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/b4ce91bd-31df-4b7d-8fd4-21a6b533276b"
+ },
+ "quota": {
+ "href": "https://api.example.org/v3/space_quotas/6da62599-4890-4a08-8b6f-180a4f47e46b"
+ },
+ "apply_manifest": {
+ "href": "https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9/actions/apply_manifest",
+ "method": "POST"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+}
+
+Retrieve all spaces the user has access to.
+ +Definition
+ +GET /v3/spaces
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of space names to filter by | +
| guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at, name |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| include | +string | +Optionally include a list of unique related resources in the response; valid value is organization |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Update a space
+Example Request
+curl "https://api.example.space/v3/spaces/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "name": "new-space-name" }'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
+ "created_at": "2017-02-01T01:33:58Z",
+ "updated_at": "2017-02-01T01:33:58Z",
+ "name": "my-space",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
+ }
+ },
+ "quota": {
+ "data": null
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
+ },
+ "apply_manifest": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest",
+ "method": "POST"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+}
+
+Definition
+ +PATCH /v3/spaces/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +New space name | +
| metadata.labels | +label object | +Labels applied to the space | +
| metadata.annotations | +annotation object | +Annotations applied to the space | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Org Manager | +
| Space Manager | +
Delete a space
+ +When a space is deleted, the user roles associated with the space will be +deleted.
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/spaces/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
| Org Manager | +
Get assigned isolation segment
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/relationships/isolation_segment" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": {
+ "guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment"
+ },
+ "related": {
+ "href": "https://api.example.org/v3/isolation_segments/e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
+ }
+ }
+}
+
+Definition
+ +GET /v3/spaces/:guid/relationships/isolation_segment
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Manage isolation segment
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/relationships/isolation_segment" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "data": {
+ "guid": "[iso-seg-guid]"
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "data": {
+ "guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment"
+ },
+ "related": {
+ "href": "https://api.example.org/v3/isolation_segments/e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
+ }
+ }
+}
+
+This endpoint assigns an isolation segment to the space. +The isolation segment must be entitled to the space’s parent organization.
+ + + +Definition
+ +PATCH /v3/spaces/:guid/relationships/isolation_segment
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-one relationship | +Isolation segment relationship, apps will run in this isolation segment; set data to null to remove the relationship |
+
Permitted roles
+ +| + |
|---|
| Admin | +
| Org Manager | +
List users for a space
+Example Request
+curl "https://api.example.org/v3/spaces/:guid/users" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/spaces/:guid/users?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/spaces/:guid/users?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/spaces/:guid/users?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "client_id",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": null,
+ "presentation_name": "client_id",
+ "origin": null,
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ }
+ }
+ },
+ {
+ "guid": "9da93b89-3f89-4f05-7238-8a2b123c79l9",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": "some-name",
+ "presentation_name": "some-name",
+ "origin": "uaa",
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9"
+ }
+ }
+ }
+ ]
+}
+
+
+Retrieve all users with a role in the specified space.
+ +Definition
+ +GET /v3/spaces/:guid/users
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of user guids to filter by | +
| usernames | +list of strings | +Comma-delimited list of usernames to filter by. Mutually exclusive with partial_usernames | +
| partial_usernames | +list of strings | +Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with usernames | +
| origins | +list of strings | +Comma-delimited list of user origins (user stores) to filter by, for example, users authenticated by UAA have the origin “uaa”; users authenticated by an LDAP provider have the origin “ldap”; when filtering by origins, usernames must be included | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at and updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Space Features
+ +Space features are used to manage whether optional capabilities are enabled for +a given space.
+ +Currently, the only space feature is SSH (ssh), which controls whether
+applications in the space may be accessed via SSH.
Note: SSH must also be enabled globally and on the app.
+The space feature object
+Example Space Feature object
+{
+ "name": "ssh",
+ "description": "Enable SSHing into apps in the space.",
+ "enabled": true
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the space feature | +
| description | +string | +Description of the space feature | +
| enabled | +boolean | +Denotes whether or not the space feature is enabled | +
Get a space feature
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/features/[name]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "name": "ssh",
+ "description": "Enable SSHing into apps in the space.",
+ "enabled": true
+}
+
+Definition
+ +GET /v3/spaces/:guid/features/:name
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
List space features
+ +This endpoint retrieves the list of features for the specified space. Currently, the only feature on spaces is the SSH feature.
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/features" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "resources": [
+ {
+ "name": "ssh",
+ "description": "Enable SSHing into apps in the space.",
+ "enabled": false
+ }
+ ]
+}
+
+Definition
+ +GET /v3/spaces/:guid/features
Permitted roles
+ +| + |
|---|
| Admin | +
| Admin Read-Only | +
| Global Auditor | +
| Org Manager | +
| Space Auditor | +
| Space Developer | +
| Space Manager | +
| Space Supporter | +
Update space features
+Example Request
+curl "https://api.example.org/v3/spaces/[guid]/features/[name]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]"
+ -d '{ "enabled": true }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "name": "ssh",
+ "description": "Enable SSHing into apps in the space.",
+ "enabled": true
+}
+
+Definition
+ +PATCH /v3/spaces/:guid/features/:name
Permitted roles
+ +| + |
|---|
| Admin | +
| Org Manager | +
| Space Manager | +
Space Quotas
+ +Space quotas are named sets of quotas. Space quota names are unique within an organization. For example, an organization may only have one space quota named “production”, but two organizations may have two distinct space quotas, both named “production”.
+ +Only one space quota may be applied to a given space at any given time.
+ +Space quotas cannot be used to bypass organization quotas. When the organization’s quota and the space’s quota specify a different values for a given resource, the more restrictive of the two is used. In the event of permissions, the more restrictive permission is used.
+The space quota object
+Example Space Quota object
+{
+ "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": null
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 20
+ },
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ },
+ "spaces": {
+ "data": [
+ {
+ "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
+ }
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the space quota | +
| created_at | +timestamp | +The time with zone when the space quota was created | +
| updated_at | +timestamp | +The time with zone when the space quota was last updated | +
| name | +string | +Name of the quota | +
| apps | +object | +Quotas that affect applications and application sub-resources | +
| apps.per_process_memory_in_mb | +integer or null |
+Maximum memory for a single process or task | +
| apps.total_memory_in_mb | +integer or null |
+Total memory allowed for all the started processes and running tasks in a space | +
| apps.total_instances | +integer or null |
+Total instances of all the started processes allowed in a space | +
| apps.log_rate_limit_in_bytes_per_second | +integer or null |
+Total log rate limit allowed for all the started processes and running tasks in an organization | +
| apps.per_app_tasks | +integer or null |
+Maximum number of running tasks in a space | +
| services | +object | +Quotas that affect services | +
| services.paid_services_allowed | +boolean | +Specifies whether instances of paid service plans can be created | +
| services.total_service_instances | +integer or null |
+Total number of service instances allowed in a space | +
| services.total_service_keys | +integer or null |
+Total number of service keys allowed in a space | +
| routes | +object | +Quotas that affect routes | +
| routes.total_routes | +integer or null |
+Total number of routes allowed in a space | +
| routes.total_reserved_ports | +integer or null |
+Total number of ports that are reservable by routes in a space | +
| relationships.organization | +to-one relationship | +A relationship to the organization where the quota belongs | +
| relationships.spaces | +to-many relationship | +A relationship to the spaces where the quota is applied | +
| links | +links object | +Links to related resources | +
Create a space quota
+Example Request
+curl "https://api.example.org/v3/space_quotas" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "production",
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "[org-guid]"
+ }
+ }
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": null
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 20
+ },
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ },
+ "spaces": {
+ "data": [
+ {
+ "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
+ }
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ }
+}
+
+This endpoint creates a new space quota scoped to a specific organization.
+ +Definition
+ +POST /v3/space_quotas
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the quota | +
| relationships.organization | +to-one relationship | +A relationship to the organization where the quota belongs | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| apps | +object | +Quotas that affect applications and application sub-resources | ++ |
| apps.per_process_memory_in_mb | +integer or null |
+Maximum memory for a single process or task | +null (infinite) | +
| apps.total_memory_in_mb | +integer or null |
+Total memory allowed for all the started processes and running tasks in a space | +null (infinite) | +
| apps.total_instances | +integer or null |
+Total instances of all the started processes allowed in a space | +null (infinite) | +
| apps.log_rate_limit_in_bytes_per_second | +integer or null |
+Total log rate limit allowed for all the started processes and running tasks in an organization | +null (infinite) | +
| apps.per_app_tasks | +integer or null |
+Maximum number of running tasks in a space | +null (infinite) | +
| services | +object | +Quotas that affect services | ++ |
| services.paid_services_allowed | +boolean | +Specifies whether instances of paid service plans can be created | +true | +
| services.total_service_instances | +integer or null |
+Total number of service instances allowed in a space | +null (infinite) | +
| services.total_service_keys | +integer or null |
+Total number of service keys allowed in a space | +null (infinite) | +
| routes | +object | +Quotas that affect routes | ++ |
| routes.total_routes | +integer or null |
+Total number of routes allowed in a space | +null (infinite) | +
| routes.total_reserved_ports | +integer or null |
+Total number of ports that are reservable by routes in a space | +null (infinite) | +
| relationships.spaces | +to-many relationship | +A relationship to the spaces where the quota is applied | ++ |
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +Org managers can create space quotas in their managed organizations | +
Get a space quota
+Example Request
+curl "https://api.example.org/v3/space_quotas/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": null
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 20
+ },
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ },
+ "spaces": {
+ "data": [
+ {
+ "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
+ }
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ }
+}
+
+Definition
+ +GET /v3/space_quotas/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Manager | +Can only query space quotas owned by affiliated organizations | +
| Space Auditor | +Can only query space quotas applied to affiliated spaces | +
| Space Developer | +Can only query space quotas applied to affiliated spaces | +
| Space Manager | +Can only query space quotas applied to affiliated spaces | +
| Space Supporter | +Can only query space quotas applied to affiliated spaces | +
Note: Response will not show any space guids that a user would not otherwise be able to see (see space view permissions).
+List space quotas
+Example Request
+curl "https://api.example.org/v3/space_quotas" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 2,
+ "total_pages": 1,
+ "first": {
+ "href": "https://api.example.org/v3/space_quotas?page=1&per_page=50"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/space_quotas?page=1&per_page=50"
+ },
+ "next": null,
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": null
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 20
+ },
+ "relationships": {
+ "organizations": {
+ "data": {
+ "guid": "9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ },
+ "spaces": {
+ "data": [
+ {
+ "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
+ }
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ }
+ },
+ {
+ "guid": "554bcf32-7032-4cb0-92bc-738f9d2089d3",
+ "created_at": "2017-05-04T17:00:41Z",
+ "updated_at": "2017-05-04T17:00:41Z",
+ "name": "sancho-panza",
+ "apps": {
+ "total_memory_in_mb": 2048,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 5,
+ "per_app_tasks": 2
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ },
+ "relationships": {
+ "organizations": {
+ "data": {
+ "guid": "9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ },
+ "spaces": {
+ "data": []
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/space_quotas/554bcf32-7032-4cb0-92bc-738f9d2089d3"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ }
+ }
+ ]
+}
+
+This endpoint lists all space quota resources that the user has permission to view (see getting a space quota).
+ +Definition
+ +GET /v3/space_quotas
| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of space quota guids to filter by | +
| names | +list of strings | +Comma-delimited list of space quota names to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| Role | +
|---|
| All Roles | +
Note: Space quotas in the response will not show any space guids that a user would not otherwise be able to see (see space view permissions).
+Update a space quota
+Example Request
+curl "https://api.example.org/v3/space_quotas/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": 5
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20,
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 4
+ }
+ }'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "f919ef8a-e333-472a-8172-baaf2c30d301",
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:41Z",
+ "name": "don-quixote",
+ "apps": {
+ "total_memory_in_mb": 5120,
+ "per_process_memory_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "total_instances": 10,
+ "per_app_tasks": null
+ },
+ "services": {
+ "paid_services_allowed": true,
+ "total_service_instances": 10,
+ "total_service_keys": 20
+ },
+ "routes": {
+ "total_routes": 8,
+ "total_reserved_ports": 20
+ },
+ "relationships": {
+ "organization": {
+ "data": {
+ "guid": "9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ },
+ "spaces": {
+ "data": [
+ {
+ "guid": "45bb0018-c38e-44c9-86d6-155c76803600"
+ }
+ ]
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301"
+ },
+ "organization": {
+ "href": "https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104"
+ }
+ }
+}
+
+This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values.
+ +Definition
+ +PATCH /v3/space_quotas/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the quota | +
| apps | +object | +Quotas that affect applications and application sub-resources | +
| apps.per_process_memory_in_mb | +integer or null |
+Maximum memory for a single process or task | +
| apps.total_memory_in_mb | +integer or null |
+Total memory of all the started processes and running tasks in a space | +
| apps.total_instances | +integer or null |
+Total instances of all the started processes in a space | +
| apps.log_rate_limit_in_bytes_per_second | +integer or null |
+Total log rate limit allowed for all the started processes and running tasks in an organization | +
| apps.per_app_tasks | +integer or null |
+Maximum number of running tasks in a space | +
| services | +object | +Quotas that affect services | +
| services.paid_services_allowed | +boolean | +If instances of paid service plans can be created | +
| services.total_service_instances | +integer or null |
+Total number of service instances in a space | +
| services.total_service_keys | +integer or null |
+Total number of service keys in a space | +
| routes | +object | +Quotas that affect routes | +
| routes.total_routes | +integer or null |
+Total number of routes that a space can have | +
| routes.total_reserved_ports | +integer or null |
+Total number of ports that all routes in a space can reserve | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +Can update space quotas in the organization where they have this role | +
Delete a space quota
+ +Space quotas cannot be deleted when applied to any spaces.
+Example Request
+curl "https://api.example.org/v3/space_quotas/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/space_quotas/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +Can delete space quotas within their managed organizations | +
Apply a space quota to a space
+Example Request
+curl "https://api.example.org/v3/space_quotas/:quota_guid/relationships/spaces" \
+-X POST \
+-H "Authorization: bearer [token]" \
+-H "Content-type: application/json" \
+-d '{
+ "data": [{ "guid": "space-guid1" }, { "guid": "space-guid2" }]
+}'
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "data": [
+ { "guid": "space-guid1" },
+ { "guid": "space-guid2" },
+ { "guid": "previous-space-guid" }
+ ],
+ "links": {
+ "self": { "href": "https://api.example.org/v3/space_quotas/quota-guid/relationships/spaces" }
+ }
+ }
+
+This endpoint applies a space quota to one or more spaces.
+ +Only an admin or an org manager in the quota’s parent organization can apply a space quota to a space.
+ +Definition
+ +POST /v3/space_quotas/:quota_guid/relationships/spaces
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| data | +to-many relationship | +Space guids that the quota will apply to | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +Can apply space quotas to spaces within their managed organizations | +
Remove a space quota from a space
+Example Request
+curl "https://api.example.org/v3/space_quotas/:quota_guid/relationships/spaces/:space_guid" \
+-X DELETE \
+-H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+This endpoint removes a space quota from a space.
+ +Only an admin or an org manager in the quota’s parent organization can remove a space quota from a space.
+ +Definition
+ +DELETE /v3/space_quotas/:quota_guid/relationships/spaces/:space_guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Org Manager | +Can remove space quotas from spaces within their managed organizations | +
Stacks
+ +Stacks are the base operating system and file system that your application will execute in. +A stack is how you configure applications to run against different operating systems +(like Windows or Linux) +and different versions of those operating systems +(like Windows 2012 or Windows 2016).
+ +An application’s lifecycle will specify which stack to execute the application in. +Buildpacks can also be associated with a particular stack if they contain stack-specific logic. +An application will automatically use buildpacks associated with the application’s configured stack.
+ +Stacks are not used for apps with a Docker lifecycle.
+The stack object
+Example Stack object
+{
+ "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
+ "created_at": "2018-11-09T22:43:28Z",
+ "updated_at": "2018-11-09T22:43:28Z",
+ "name": "my-stack",
+ "description": "Here is my stack!",
+ "build_rootfs_image": "my-stack",
+ "run_rootfs_image": "my-stack",
+ "default": true,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the stack | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| name | +string | +The name of the stack | +
| description | +string | +The description of the stack | +
| build_rootfs_image | +_string | +The name of the stack image associated with staging/building Apps. If a stack does not have unique images, this will be the same as the stack name. | +
| run_rootfs_image | +_string | +The name of the stack image associated with running Apps + Tasks. If a stack does not have unique images, this will be the same as the stack name. | +
| default | +boolean | +Whether the stack is configured to be the default stack for new applications. | +
| metadata.labels | +label object | +Labels applied to the stack | +
| metadata.annotations | +annotation object | +Annotations applied to the stack | +
| links | +links object | +Links to related resources | +
Create a stack
+Example Request
+curl "https://api.example.org/v3/stacks" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "name": "my-stack",
+ "description": "Here is my stack!",
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+ "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
+ "created_at": "2018-11-09T22:43:28Z",
+ "updated_at": "2018-11-09T22:43:28Z",
+ "name": "my-stack",
+ "description": "Here is my stack!",
+ "build_rootfs_image": "my-stack",
+ "run_rootfs_image": "my-stack",
+ "default": true,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
+ }
+ }
+}
+
+Definition
+ +POST /v3/stacks
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| name | +string | +Name of the stack; must be unique and no longer than 250 characters | +
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| description | +string | +Description of the stack; must no longer than 250 characters | +null |
+
| metadata.labels | +label object | +Labels applied to the stack | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the stack | ++ |
Permitted roles
+ +| + |
|---|
| Admin | +
Get a stack
+Example Request
+curl "https://api.example.org/v3/stacks/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
+ "created_at": "2018-11-09T22:43:28Z",
+ "updated_at": "2018-11-09T22:43:28Z",
+ "name": "my-stack",
+ "description": "Here is my stack!",
+ "build_rootfs_image": "my-stack",
+ "run_rootfs_image": "my-stack",
+ "default": true,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
+ }
+ }
+}
+
+Definition
+ +GET /v3/stacks/:guid
Permitted roles
+ +| + |
|---|
| All Roles | +
List stacks
+Example Request
+curl "https://api.example.org/v3/stacks" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/stacks?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/stacks?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/stacks?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
+ "created_at": "2018-11-09T22:43:28Z",
+ "updated_at": "2018-11-09T22:43:28Z",
+ "name": "my-stack-1",
+ "build_rootfs_image": "my-stack-1-build",
+ "run_rootfs_image": "my-stack-1-run",
+ "description": "This is my first stack!",
+ "default": true,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
+ }
+ }
+ },
+ {
+ "guid": "81c916c9-c2f9-440e-8e73-102e79c4704h",
+ "created_at": "2018-11-09T22:43:29Z",
+ "updated_at": "2018-11-09T22:43:29Z",
+ "name": "my-stack-2",
+ "description": "This is my second stack!",
+ "build_rootfs_image": "my-stack-2-build",
+ "run_rootfs_image": "my-stack-2-run",
+ "default": false,
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/stacks/81c916c9-c2f9-440e-8e73-102e79c4704h"
+ }
+ }
+ }
+ ]
+}
+
+
+Retrieve all stacks.
+ +Definition
+ +GET /v3/stacks
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| names | +list of strings | +Comma-delimited list of stack names to filter by | +
| default | +boolean | +If true, only return the default stack | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at, updated_at, and name |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List apps on a stack
+Example Request
+curl "https://api.example.org/v3/stacks/[guid]/apps" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
+ "name": "my_app",
+ "state": "STARTED",
+ "created_at": "2016-03-17T21:41:30Z",
+ "updated_at": "2016-03-18T11:32:30Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["java_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "current_droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ },
+ {
+ "guid": "02b4ec9b-94c7-4468-9c23-4e906191a0f8",
+ "name": "my_app2",
+ "state": "STOPPED",
+ "created_at": "1970-01-01T00:00:02Z",
+ "updated_at": "2016-06-08T16:41:26Z",
+ "lifecycle": {
+ "type": "buildpack",
+ "data": {
+ "buildpacks": ["ruby_buildpack"],
+ "stack": "cflinuxfs4"
+ }
+ },
+ "relationships": {
+ "space": {
+ "data": {
+ "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
+ }
+ },
+ "droplet": {
+ "data": {
+ "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
+ },
+ "space": {
+ "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
+ },
+ "processes": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes"
+ },
+ "packages": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages"
+ },
+ "environment_variables": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables"
+ },
+ "current_droplet": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current"
+ },
+ "droplets": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets"
+ },
+ "tasks": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks"
+ },
+ "start": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start",
+ "method": "POST"
+ },
+ "stop": {
+ "href": "https://api.example.org/v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop",
+ "method": "POST"
+ },
+ "revisions": {
+ "href": "https://api.example.org//v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions"
+ },
+ "deployed_revisions": {
+ "href": "https://api.example.org//v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed"
+ },
+ "features": {
+ "href": "https://api.example.org//v3/stacks/[guid]/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/features"
+ }
+ },
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ }
+ }
+ ]
+ }
+
+Retrieve all apps using a given stack.
+ +Definition
+ +GET /v3/stacks/:guid/apps
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at, updated_at, and name |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
Update a stack
+Example Request
+curl "https://api.example.org/v3/stacks/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
+ "created_at": "2018-11-09T22:43:28Z",
+ "updated_at": "2018-11-09T22:43:28Z",
+ "name": "my-stack",
+ "description": "Here is my stack!",
+ "build_rootfs_image": "my-stack",
+ "run_rootfs_image": "my-stack",
+ "default": true,
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/stacks/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the stack | +
| metadata.annotations | +annotation object | +Annotations applied to the stack | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Delete a stack
+Example Request
+curl "https://api.example.org/v3/stacks/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 204 No Content
+Definition
+ +DELETE /v3/stacks/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
Tasks
+ +Tasks are one-off jobs that are intended to perform a task, stop, and be cleaned up, freeing up resources.
+ +Examples of this include database migrations, sending things, and batch jobs.
+The task object
+Example Task object
+{
+ "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
+ "sequence_id": 1,
+ "name": "migrate",
+ "command": "rake db:migrate",
+ "state": "RUNNING",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": null
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+}
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the task | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| sequence_id | +integer | +User-facing id of the task; this number is unique for every task associated with a given app | +
| name | +string | +Name of the task | +
| command | +string | +Command that will be executed; this field may be excluded based on a user’s role | +
| state | +string | +State of the task Possible states are PENDING, RUNNING, SUCCEEDED, CANCELING, and FAILED |
+
| memory_in_mb | +integer | +Amount of memory to allocate for the task in MB | +
| disk_in_mb | +integer | +Amount of disk to allocate for the task in MB | +
| log_rate_limit_per_second | +integer | +Amount of log rate to allocate for the task in bytes | +
| result | +object | +Results from the task | +
| result.failure_reason | +string | +Null if the task succeeds, contains the error message if it fails | +
| droplet_guid | +uuid | +The guid of the droplet that will be used to run the command | +
| relationships.app | +timestamp | +The app the task belongs to | +
| metadata.labels | +label object | +Labels applied to the task | +
| metadata.annotations | +annotation object | +Annotations applied to the task | +
| links | +links object | +Links to related resources | +
Create a task
+Example Request with Command
+curl "https://api.example.org/v3/apps/[guid]/tasks" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{ "command": "rake db:migrate" }'
+Example Request with Template Process
+curl "https://api.example.org/v3/apps/[guid]/tasks" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{ "template": { "process": {"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e"} } }'
+Example Response
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+
+{
+ "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
+ "sequence_id": 1,
+ "name": "migrate",
+ "command": "rake db:migrate",
+ "state": "RUNNING",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": null
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+}
+
+Definition
+ +POST /v3/apps/:guid/tasks
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| command[1] | +string | +Command that will be executed; NOTE: optional if a template.process.guid is provided |
+
Optional parameters
+ +| Name | +Type | +Description | +Default | +
|---|---|---|---|
| name | +string | +Name of the task | +auto-generated | +
| disk_in_mb[1] | +integer | +Amount of disk to allocate for the task in MB | +operator-configured default_app_disk_in_mb |
+
| memory_in_mb[1] | +integer | +Amount of memory to allocate for the task in MB | +operator-configured default_app_memory |
+
| log_rate_limit_per_second[1] | +integer | +Amount of log rate to allocate for the task in bytes | +operator-configured default_app_log_rate_limit_in_bytes_per_second |
+
| droplet_guid | +uuid | +The guid of the droplet that will be used to run the command | +the app’s current droplet | +
| template.process.guid | +uuid | +The guid of the process that will be used as a template | +null |
+
| metadata.labels | +label object | +Labels applied to the package | ++ |
| metadata.annotations | +annotation object | +Annotations applied to the package | ++ |
1 If not provided, and a template.process.guid is provided, this field will use the value from the process with the given guid.
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Get a task
+Example Request
+curl "https://api.example.org/v3/tasks/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
+ "sequence_id": 1,
+ "name": "migrate",
+ "command": "rake db:migrate",
+ "state": "RUNNING",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": null
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+}
+
+Retrieve a specific task. The command field may be excluded
+in the response based on the user’s role.
Definition
+ +GET /v3/tasks/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | +command field redacted |
+
| Org Manager | +command field redacted |
+
| Space Auditor | +command field redacted |
+
| Space Developer | ++ |
| Space Manager | +command field redacted |
+
| Space Supporter | +command field redacted |
+
List tasks
+Example Request
+curl "https://api.example.org/v3/tasks" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/tasks?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/tasks?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/tasks?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
+ "sequence_id": 1,
+ "name": "hello",
+ "state": "SUCCEEDED",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": null
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+ },
+ {
+ "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
+ "sequence_id": 2,
+ "name": "migrate",
+ "state": "FAILED",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": "Exited with status 1"
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve all tasks the user has access to. The command field is excluded in the response.
Definition
+ +GET /v3/tasks
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of task guids to filter by | +
| names | +list of strings | +Comma-delimited list of task names to filter by | +
| states | +list of strings | +Comma-delimited list of task states to filter by | +
| app_guids | +list of strings | +Comma-delimited list of app guids to filter by | +
| space_guids | +list of strings | +Comma-delimited list of space guids to filter by | +
| organization_guids | +list of strings | +Comma-delimited list of organization guids to filter by | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| + |
|---|
| All Roles | +
List tasks for an app
+Example Request
+curl "https://api.example.org/v3/apps/:guid/tasks" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
+ "sequence_id": 1,
+ "name": "hello",
+ "state": "SUCCEEDED",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": null
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+ },
+ {
+ "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
+ "sequence_id": 2,
+ "name": "migrate",
+ "state": "FAILED",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": "Exited with status 1"
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+ }
+ ]
+}
+
+Retrieve tasks for an app the user has access to. The command field may be
+excluded in the response based on the user’s role.
Definition
+ +GET /v3/apps/:guid/tasks
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of task guids to filter by | +
| names | +list of strings | +Comma-delimited list of task names to filter by | +
| states | +list of strings | +Comma-delimited list of task states to filter by | +
| sequence_ids | +list of strings | +Comma delimited list of sequence ids to filter by Valid values are integers >= 1 | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | +command field redacted |
+
| Org Manager | +command field redacted |
+
| Space Auditor | +command field redacted |
+
| Space Developer | ++ |
| Space Manager | +command field redacted |
+
| Space Supporter | +command field redacted |
+
Update a task
+Example Request
+curl "https://api.example.org/v3/tasks/[guid]" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-Type: application/json" \
+ -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
+
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
+ "sequence_id": 1,
+ "name": "migrate",
+ "command": "rake db:migrate",
+ "state": "RUNNING",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": null
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {"key":"value"},
+ "annotations": {"note":"detailed information"}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+}
+
+Definition
+ +PATCH /v3/tasks/:guid
Optional parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the task | +
| metadata.annotations | +annotation object | +Annotations applied to the task | +
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
Cancel a task
+Example Request
+curl "https://api.example.org/v3/tasks/[guid]/actions/cancel" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+
+{
+ "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
+ "sequence_id": 1,
+ "name": "migrate",
+ "command": "rake db:migrate",
+ "state": "CANCELING",
+ "memory_in_mb": 512,
+ "disk_in_mb": 1024,
+ "log_rate_limit_in_bytes_per_second": 1024,
+ "result": {
+ "failure_reason": null
+ },
+ "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
+ "metadata": {
+ "labels": {},
+ "annotations": {}
+ },
+ "created_at": "2016-05-04T17:00:41Z",
+ "updated_at": "2016-05-04T17:00:42Z",
+ "relationships": {
+ "app": {
+ "data": {
+ "guid": "ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ }
+ }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
+ },
+ "app": {
+ "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
+ },
+ "cancel": {
+ "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
+ "method": "POST"
+ },
+ "droplet": {
+ "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
+ }
+ }
+}
+
+Cancels a running task.
+ +Canceled tasks will initially be in state CANCELING and will move to state FAILED once the cancel request has been processed.
Cancel requests are idempotent and will be processed according to the state of the task when the request is executed.
+ +Canceling a task that is in SUCCEEDED or FAILED state will return an error.
Definition
+ +POST /v3/tasks/:guid/actions/cancel
+PUT /v3/tasks/:guid/cancel (Deprecated)
Permitted roles
+ +| + |
|---|
| Admin | +
| Space Developer | +
| Space Supporter | +
Users
+ +Every Cloud Foundry action (pushing an application, creating a space) requires a +user. Each Cloud Foundry installation has one pre-installed user, admin, which +can create subsequent users. Users can be assigned roles which give them +privileges to perform actions. For example, the Space Developer role grants a +user permission to manage apps and services in a space (to push apps, scale +apps, delete apps).
+The user object
+Example User object
+ {
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": "some-name",
+ "presentation_name": "some-name",
+ "origin": "uaa",
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ }
+ }
+ }
+
+| Name | +Type | +Description | +
|---|---|---|
| guid | +uuid | +Unique identifier for the user | +
| created_at | +timestamp | +The time with zone when the object was created | +
| updated_at | +timestamp | +The time with zone when the object was last updated | +
| username | +string | +The name registered in UAA; will be null for UAA clients and non-UAA users |
+
| presentation_name | +string | +The name displayed for the user; for UAA users, this is the same as the username. For UAA clients, this is the UAA client ID | +
| origin | +string | +The identity provider for the UAA user; will be null for UAA clients |
+
| metadata.labels | +label object | +Labels applied to the user | +
| metadata.annotations | +annotation object | +Annotations added to the user | +
| links | +links object | +Links to related resources | +
Create a user
+ +Creating a user requires one value, a GUID. This creates a user in the Cloud +Controller database.
+ +Generally, the GUID should match the GUID of an already-created user in the +UAA database, though this is not required.
+Example Request
+curl "https://api.example.org/v3/users" \
+ -X POST \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+ {
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": "some-name",
+ "presentation_name": "some-name",
+ "origin": "uaa",
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ }
+ }
+ }
+
+Definition
+ +POST /v3/users
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guid | +string | +Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user’s GUID; in the case of UAA clients, this will match the UAA client ID | +
| metadata.labels | +label object | +Labels applied to the user | +
| metadata.annotations | +annotation object | +Annotations added to the user | +
Permitted roles
+ +| + |
|---|
| Admin | +
Get a user
+Example Request
+curl "https://api.example.org/v3/users/[guid]" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+ {
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": "some-name",
+ "presentation_name": "some-name",
+ "origin": "uaa",
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ }
+ }
+ }
+
+Definition
+ +GET /v3/users/:guid
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Auditor | +Can only view users affiliated with their org | +
| Org Billing Manager | +Can only view users affiliated with their org | +
| Org Manager | +Can only view users affiliated with their org | +
| Space Auditor | +Can only view users affiliated with their org | +
| Space Developer | +Can only view users affiliated with their org | +
| Space Manager | +Can only view users affiliated with their org | +
| Space Supporter | +Can only view users affiliated with their org | +
Note: A user can always see themselves with this endpoint, regardless of role.
+List users
+Example Request
+curl "https://api.example.org/v3/users" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "pagination": {
+ "total_results": 3,
+ "total_pages": 2,
+ "first": {
+ "href": "https://api.example.org/v3/users?page=1&per_page=2"
+ },
+ "last": {
+ "href": "https://api.example.org/v3/users?page=2&per_page=2"
+ },
+ "next": {
+ "href": "https://api.example.org/v3/users?page=2&per_page=2"
+ },
+ "previous": null
+ },
+ "resources": [
+ {
+ "guid": "client_id",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": null,
+ "presentation_name": "client_id",
+ "origin": null,
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ }
+ }
+ },
+ {
+ "guid": "9da93b89-3f89-4f05-7238-8a2b123c79l9",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": "some-name",
+ "presentation_name": "some-name",
+ "origin": "uaa",
+ "metadata": {
+ "labels": {},
+ "annotations":{}
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9"
+ }
+ }
+ }
+ ]
+}
+
+
+Retrieve all users that the current user can see.
+ +Definition
+ +GET /v3/users
Query parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| guids | +list of strings | +Comma-delimited list of user guids to filter by | +
| usernames | +list of strings | +Comma-delimited list of usernames to filter by. Mutually exclusive with partial_usernames | +
| partial_usernames | +list of strings | +Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with usernames | +
| origins | +list of strings | +Comma-delimited list of user origins (user stores) to filter by, for example, users authenticated by UAA have the origin “uaa”; users authenticated by an LDAP provider have the origin “ldap”; when filtering by origins, usernames must be included | +
| page | +integer | +Page to display; valid values are integers >= 1 | +
| per_page | +integer | +Number of results per page; valid values are 1 through 5000 |
+
| order_by | +string | +Value to sort by. Defaults to ascending; prepend with - to sort descendingValid values are created_at and updated_at |
+
| label_selector | +string | +A query string containing a list of label selector requirements | +
| created_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
| updated_ats | +timestamp | +Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators | +
Permitted roles
+ +| Role | +Notes | +
|---|---|
| Admin | ++ |
| Admin Read-Only | ++ |
| Global Auditor | ++ |
| Org Auditor | +Can only view users affiliated with their org | +
| Org Billing Manager | +Can only view users affiliated with their org | +
| Org Manager | +Can only view users affiliated with their org | +
| Space Auditor | +Can only view users affiliated with their org | +
| Space Developer | +Can only view users affiliated with their org | +
| Space Manager | +Can only view users affiliated with their org | +
| Space Supporter | +Can only view users affiliated with their org | +
Update a user
+ +Update a user’s metadata.
+Example Request
+curl "https://api.example.org/v3/users/24d59a1e-2613-4255-86a2-e0454cc6e261" \
+ -X PATCH \
+ -H "Authorization: bearer [token]" \
+ -H "Content-type: application/json" \
+ -d '{
+ "metadata": {
+ "labels": { "environment": "production" },
+ "annotations": { "note": "detailed information" }
+ }
+ }'
+Example Response
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+ {
+ "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+ "created_at": "2019-03-08T01:06:19Z",
+ "updated_at": "2019-03-08T01:06:19Z",
+ "username": "some-name",
+ "presentation_name": "some-name",
+ "origin": "uaa",
+ "metadata": {
+ "labels": { "enviroment": "production" },
+ "annotations": { "note": "detailed information" }
+ },
+ "links": {
+ "self": {
+ "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+ }
+ }
+ }
+
+Definition
+ +PATCH /v3/users/:guid
Required parameters
+ +| Name | +Type | +Description | +
|---|---|---|
| metadata.labels | +label object | +Labels applied to the app | +
| metadata.annotations | +annotation object | +Annotations added to the user | +
Permitted roles
+ +| + |
|---|
| Admin | +
Delete a user
+ +All roles associated with a user will be deleted if the user is deleted.
+Example Request
+curl "https://api.example.org/v3/users/[guid]" \
+ -X DELETE \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 202 Accepted
+Location: https://api.example.org/v3/jobs/[guid]
+Definition
+ +DELETE /v3/users/:guid
Permitted roles
+ +| + |
|---|
| Admin | +
Experimental Resources
+Upgrade Guide
+ +This document is intended to help client authors upgrade from Cloud Foundry’s V2 API to the V3 API.
+ +When moving to the V3 API, it is important to understand that the V3 API is backed by the same database as the V2 API. Though resources may be presented differently and have different interaction patterns, the internal state of CF is the same across both APIs. If you create an organization using the V3 API, +it will be visible to the V2 API, and vice-versa.
+ +If you have questions, need help, or want to chat about the upgrade process, please reach out to us in Cloud Foundry Slack.
+Conceptual Changes
+App Sub-Resources
+ +The V2 API rolls up several resources into its representation of an “app”:
+ +-
+
- Packages: Source assets for the application +
- Droplets: Staged, executable assets for the application +
- Builds: Configuration for how to stage the package into a droplet +
- 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:
+ +-
+
- Staging a previous package into a new droplet +
- Rolling back to a previous droplet +
- Staging a droplet to run a task, without running any processes +
- 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:
+ +-
+
- The app resource contains much less information about the application as a whole +
- An application can have multiple processes, each with their own start command. The processes can be scaled independently, and stats be retrieved independently. +
- An application might not be running with its most recent package or droplet +
Starting Apps
+ +In the V2 API, starting an app (PUT /v2/apps/:GUID with state: STARTED) will automatically stage new packages into droplets. In V3, starting an app will only run the app’s current droplet. This change gives clients more control over what package to stage and when to stage it.
To reproduce the V2 start behavior in V3:
+ +
-
+
- List packages and filter on package state with value
READYand order by recency.
+ - If a package has been turned into a droplet (see this endpoint) this means it has been staged already. In V2 workflows, this would mean this package is what the current droplet is running. +
- Stage the package by creating a build. This turns your package into a droplet. +
- Update the app’s current droplet to the selected droplet. This droplet will be run when the app starts. +
- Change the app’s state to started +
This gives V3 users more flexibility when managing applications. The following +diagram shows many different flows for starting an app.
+ +
Apps can upload multiple packages, stage multiple droplets, roll back to older droplets, and other complicated workflows.
+Asynchronous Operations
+ +Unlike V2, clients cannot opt-in for asynchronous responses from endpoints.
+Instead, endpoints that require asynchronous processing will return 202 Accepted with a Location header pointing to the job resource to poll.
+Endpoints that do not require asynchronous processing will respond synchronously.
For clients that want to report the outcome of an asynchronous operation, poll the job in the Location header until its state is no longer PROCESSING.
+If the job’s state is FAILED, the errors field will contain any errors that occurred during the operation.
An example of an asynchronous endpoint is the delete app endpoint.
+ +Service related endpoints such as service instance, service credential binding and service route binding may create jobs
+that transition to state POLLING after PROCESSING. This state reflects the polling of the last operation from the service broker.
+For clients that want to report the outcome of this asynchronous operation, poll the job in the Location header until its state is no longer POLLING.
Read more about the job resource.
+ + +Errors
+Example Request
+curl "https://api.example.org/v2/apps/not-found" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+
+{
+ "description": "The app could not be found: not-found",
+ "error_code": "CF-AppNotFound",
+ "code": 100004
+}
+Example Request
+curl "https://api.example.org/v3/apps/not-found" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+
+{
+ "errors": [
+ {
+ "detail": "App not found",
+ "title": "CF-ResourceNotFound",
+ "code": 10010
+ }
+ ]
+}
+The V3 API returns an array of errors instead of a single error like in V2.
+ +Clients may wish to display all returned errors.
+Filtering
+Filters are specified as individual query parameters in V3
+curl "https://api.example.org/v2/apps?q=name+IN+dora,broker;stack:cflinuxfs4" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+curl "https://api.example.org/v3/apps?names=dora,broker&stacks=cflinuxfs4" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Filtering resources no longer uses V2’s query syntax. See the example to the right.
+ +A few common filters have been also renamed in V3:
+ +| V2 filter | +V3 filter | +
|---|---|
results-per-page |
+per_page |
+
page |
+page |
+
order-by |
+order_by |
+
order-direction |
+N/A1 | +
1 In V3, order is ascending by default. Prefix the order_by value with - to make it descending. For example, ?order_by=-name would order a list of resources by name in descending order.
Filtering inequalities has changed in V3: V3 dispenses with the q= preamble,
+uses created_ats instead of timestamp and uses bracket operators ([lt],
+[gt], [lte], [gte]). For example, to request all audit events occurring on
+New Year’s Day, one would use the following query: GET
+/v3/audit_events?created_ats[lt]=2020-01-02T00:00:00Z&created_ats[gt]=2019-12-31T23:59:59Z.
The corresponding V2 query would be GET
+/v2/events?q=timestamp<2020-01-02T00:00:00Z&q=timestamp>2019-12-31T23:59:59Z.
Filtering on equality has also changed: V3 dispenses with the q= preamble and
+uses the pluralized field (e.g. names) on the left side of the equals sign.
+For filtering on inclusion in a set, V3 allows passing multiple values separated
+by commas.
For example, to request the organizations by
+their name (“finance” and “marketing”), one would use the following query:
+/v3/organizations?names=finance,marketing
The corresponding V2 query would be GET
+/v2/organizations?q=name%20IN%20finance,marketing
Read more about filtering in V3.
+Including Associated Resources
+ +The inline-relations-depth parameter is no longer supported on V3. Instead, some resources support the include parameter to selectively include associated resources in the response body.
For example, to include an app’s space in the response:
+
+cf curl /v3/apps/:guid?include=space
+
In addition, some resources provide the possibility of including specified fields of a related resource.
+ +For example, to include the service broker name and guid in the service offering’s response:
+
+cf curl /v3/service_offerings/:guid?fields[service_broker]=name,guid
+
Read more about the include parameter and the fields parameter.
Resource Summaries
+ +V2 provided several endpoints that returned rolled-up summaries (e.g.
+/v2/spaces/:guid/summary for a space summary, or
+/v2/organizations/:guid/summary for an organization summary). Although
+convenient, these endpoints have been largely removed from V3, for they were
+computationally expensive and often returned much more information than
+needed.
In V3, to enable better API performance, these usage patterns are
+deliberately disallowed. Instead, clients are encouraged to think more carefully
+about which information they need and to fetch that information with
+multiple API calls and/or by making use of the include
+parameter or the fields parameter on certain endpoints.
In V2, summary endpoints provided a way to fetch all resources associated with a +parent resource. In V3, fetch the summary though the associated resource and +filter by the parent resource. See below for examples of summaries in V3.
+ +Replacing the space summary endpoint
+ +-
+
- To fetch all apps in a space, use
GET /v3/apps?space_guids=<space-guid>. +Passinginclude=spacewill include the space resource in the response body.
+ - To fetch all service offerings in a space use
GET +/v3/service_offerings?space_guids=<space-guid>. Use the +fieldsparameter to include related information in the response +body.
+ - To fetch all service instances in a space use
GET +/v3/service_instances?space_guids=<space-guid>. Use the +fieldsparameter to include related information in the response +body.
+
Replacing the space summary response for service instances
+ +Similar fields to what /v2/spaces/:guid/summary was offering for services are available from v3 endpoints.
The table below describes the query parameters needed to retrieve some of those fields using /v3/service_instances endpoint.
+Same query parameters are available on the request for a single resource.
| V2 summary fields | +V3 query | +V3 response fields | +
|---|---|---|
| services[].service_plan.guid | +fields[service_plan]=guid | +resources[].included.service_plans[].guid | +
| services[].service_plan.name | +fields[service_plan]=name | +resources[].included.service_plans[].name | +
| services[].service_plan.service.guid | +fields[service_plan.service_offering]=guid | +resources[].included.service_offerings[].guid | +
| services[].service_plan.service.label | +fields[service_plan.service_offering]=name | +resources[].included.service_offerings[].name | +
| services[].service_broker_name | +fields[service_plan.service_offering.service_broker]=name | +resources[].included.service_brokers[].name | +
| shared_from.space_guid | +fields[space]=guid | +resources[].included.spaces[].guid | +
| shared_from.space_name | +fields[space]=name | +resources[].included.spaces[].name | +
| shared_from.organization_name | +fields[space.organization]=name | +resources[].included.organizations[].name | +
The table below describes the query parameters needed to retrieve the sharing information using /v3/service_instances/:guid/relationships/shared_spaces endpoint.
| V2 summary fields | +V3 query | +V3 response fields | +
|---|---|---|
| shared_to.space_guid | +fields[space]=guid | +included.spaces[].guid | +
| shared_to.space_name | +fields[space]=name | +included.spaces[].name | +
| shared_to.organization_name | +fields[space.organization]=name | +included.organizations[].name | +
The existing bound_app_count field can be found by using the usage summary endpoint
Read more about the fields parameter.
Replacing the user summary endpoint
+ +-
+
- The user summary was useful for finding organizations and spaces where a user
+had roles. In V3, with the introduction of the role resource, you can use
GET +/v3/roles?user_guids=<user-guid>to list a user’s roles. Passing +include=space,organizationwill include the relevant spaces and organizations +in the response body.
+
Usage summary endpoints
+ +There are still a couple of endpoints in V3 that provide a basic summary of +instance and memory usage. See the org summary and +platform summary endpoints.
+New Concepts
+Actions
+ +Actions are API requests that are expected to immediately initiate change within the Cloud Foundry runtime. This is differentiated from requests which update a record but require additional updates, such as restarting an app, to cause changes to a resource to take effect.
+ +Example:
+
+POST /v3/apps/:guid/actions/start
+
Links
+Example Request
+curl "https://api.example.org/v3/apps/:guid" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+{
+ "...": "...",
+ "links": {
+ "self": {
+ "href": "http://api.example.com/v3/apps/:guid"
+ },
+ "space": {
+ "href": "http://api.example.com/v3/spaces/:space_guid"
+ }
+ }
+}
+Links provide URLs to associated resources, relationships, and actions for a resource. +The example links to both the app itself and the space in which it resides.
+ + +Metadata
+Example Request
+curl "https://api.example.org/v3/:resource/:guid" \
+ -X GET \
+ -H "Authorization: bearer [token]"
+Example Response
+{
+ "...": "...",
+ "metadata": {
+ "labels": {
+ "environment": "production",
+ "internet-facing": "false"
+ },
+ "annotations": {
+ "contacts": "Bill tel(1111111) email(bill@fixme)"
+ }
+ }
+}
+Metadata allows you to tag and query certain API resources with information; metadata does not affect the resource’s functionality.
+ +For more details and usage examples, see metadata or official CF docs.
+ +Note that metadata consists of two keys, labels and annotations, each of which consists of key-value pairs. API V3 allows filtering by labels (see label_selector) but not by annotations.
Relationships
+Example Request
+curl "https://api.example.org/v3/apps" \
+ -X POST \
+ -H "Authorization: bearer [token]"
+ -d '{
+ "name": "testapp",
+ "relationships": {
+ "space": { "data": { "guid": "1234" }}
+ }
+ }'
+Relationships represent associations between resources: For example, every space belongs in an organization, and every app belongs in a space. The V3 API can create, read, update, and delete these associations.
+ +In the example request we create an app with a relationship to a specific space.
+ +One can retrieve or update a resource’s relationships. For example, to retrieve an app’s relationship to its space with the /v3/apps/:app_guid/relationships/space endpoint.
For more information, refer to the relationships.
+New Resources
+ +The V3 API introduces new resources that are not available on the V2 API. Below are brief descriptions of these resources. This is not intended to be an exhaustive list and may not be updated as new resources are added to V3.
+ +Note: Some of these resources may still be experimental and are subject to change or removal without warning. For up to date information on which resources are still experimental see Experimental Resources.
+ + +App Features
+ +App features support enabling/disabling behaviors for an individual app.
+ +Read more about the app feature resource.
+ + +Builds
+ +Builds increase the flexibility and granularity of control available +to clients crafting stagings workflows. For example:
+ +-
+
- Staging older packages instead of always staging the most recent package +
- Staging packages without having to stop an application +
- Staging packages to produce droplets without setting them as the current +droplet for an app +
- Staging packages into droplets for use in tasks and/or rolling deployments +
Read more about the builds resource.
+ + +Deployments
+ +Deployments are objects that manage updates to applications with zero downtime.
+ +Read more about the deployments resource.
+ + +Isolation Segments
+ +Isolation segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.
+ +Read more about the isolation segment resource.
+ + +Manifests
+ +Manifests are a method for providing bulk configuration to applications and other resources.
+ +Read more about the manifest resource.
+ + +Revisions
+ +Revisions represent code and configuration used by an application at a specific time. The most recent revision for a running application represents the code and configuration currently running in Cloud Foundry.
+ +Read more about the revision resource.
+Service Route Bindings
+ +There is a new resource service route binding that represents a binding between a route and a service instance.
Creation/Deletion of these bindings is therefore done via that endpoint in v3.
+ +This resource also supports metadata both in create and update requests.
+Audit event of type audit.service_route_binding.update is recorded when metadata update is requested.
It has a nested resource for fetching binding parameters from the broker. Parameters are only set during creation.
+ +Read more about the service route binding resource.
+ + +Sidecars
+ +Sidecars are additional programs that are run in the same container as a process.
+ +Read more about the sidecar resource.
+ + +Tasks
+ +Tasks are one-off jobs that are intended to execute a droplet, stop, and be cleaned up, freeing up resources.
+ +Examples of this include database migrations and running batch jobs.
+ +Read more about the task resource.
+Changed Resources
+ +This table shows how V2 resources map to their respective V3 counterparts. Note that some V2 resources have split into multiple V3 resources, and some V2 resources have been combined into a single resource on V3. As these resources are currently under active development, these mappings may change.
+ +| V2 Resource(s) | +V3 Resource(s) | +Details | +
|---|---|---|
| Apps | +Apps, Builds, Droplets, Packages, Processes | ++ |
| Buildpacks | +Buildpacks | ++ |
| Domains, Shared Domains, Private Domains | +Domains | +Domains in V3 | +
| Environment Variable Groups | +Environment Variable Groups | ++ |
| Events | +Audit Events | +Audit Events in V3 | +
| Feature Flags | +Feature Flags | ++ |
| Info | +Info | +Info in V3 | +
| Jobs | +Jobs | ++ |
| Organizations | +Organizations | ++ |
| Quota Definitions | +Organization Quotas | +Organization Quotas in V3 | +
| Resource Matches | +Resource Matches | ++ |
| Routes, Route Mappings | +Routes, Destinations | +Routes in V3 | +
| Security Groups | +Security Groups | +Security Groups in V3 | +
| Services | +Service Offerings | +Service Offerings in V3 | +
| Service Bindings, Service Keys | +Service Keys | ++ |
| Service Brokers | +Service Brokers | +Service Brokers in V3 | +
| Service Instances, User-Provided Service Instances | +Service Instances | ++ |
| Service Plans | +Service Plans | +Service Plans in V3 | +
| Service Plan Visibilities | +Service Plan Visibility | +Service Plan Visibility in V3 | +
| Spaces | +Spaces | ++ |
| Space Quota Definitions | +Space Quotas | +Space Quotas in V3 | +
| Stacks | +Stacks | ++ |
| Usage Events | +Usage Events | +Usage Events in V3 | +
| Users | +Roles, Users | +Users and Roles in V3 | +
Audit Events in V3
+ +In V2, these were called “events” (e.g. /v2/events). In V3, we adopt the term
+“audit events” to better distinguish them from usage events.
V2 audit events contained information about the “actee” (the resource that the +event affected). V3 audit events refer to the affected resource as the “target”.
+ +V2 audit events had a timestamp field. In V3, this field has been renamed to
+created_at for consistency with other resources. The value is the same.
In general, V3 audit events contain all of the same information that they +contained in V2, but the JSON is structured a little differently. In particular:
+ +-
+
- The
metadatafield has been renamed todata.
+ - Actor-related fields have been grouped into an object under the
actorkey +(e.g.actor.typeinstead ofactor_type).
+ - Actee-related fields have been grouped under the
targetkey (e.g. +target.typeinstead ofactee_type).
+
V3 endpoints attempt to report audit events in the same way as V2 endpoints did.
+A notable case where this was not possible is for the audit.app.restage event.
+Read more about restaging in V3.
Read more about the audit event resource.
+Domains in V3
+ +In V2, there were two types of domains exposed via different endpoints: private domains and shared domains.
+ +In V3, there is only one domain resource. A domain is “private” if it has an “owning organization”, which is the organization in which the domain is accessible. This is represented as a relationship to this organization. A domain is “shared” if it doesn’t have this relationship.
+ +Read more about the domain resource.
+Info in V3
+ +In V2, /v2/info provides descriptive information about the system and endpoints to external APIs.
In V3, /v3/info only provides descriptive information about the system.
To access the external APIs in V3, use the root (/).
Organization Quotas in V3
+ +In V2, -1 represented an unlimited value for a quota limit.
In V3, null is used to represent an unlimited value.
The names of the limit fields have changed from V2 to V3.
+ +| V2 | +V3 | +
|---|---|
| non_basic_services_allowed | +services.paid_services_allowed | +
| total_services | +services.total_service_instances | +
| total_service_keys | +services.total_service_keys | +
| total_routes | +routes.total_routes | +
| total_reserved_route_ports | +routes.total_reserved_ports | +
| total_private_domains | +domains.total_domains | +
| memory_limit | +apps.total_memory_in_mb | +
| instance_memory_limit | +apps.per_process_memory_in_mb | +
| app_instance_limit | +apps.total_instances | +
| app_task_limit | +apps.per_app_tasks | +
Read more about the organization quota resource.
+Routes in V3
+ +In V2, the route resource represented a URL that could be mapped to an app, and the route mapping resource represented a mapping between a route and an app.
+ +In V3, these concepts have been collapsed into a single route resource. Now, a route can have one or more “destinations” listed on it. These represent a mapping from the route to a resource that can serve traffic (e.g. a process of an app).
+ +Read more about routes, destinations, and ports.
+Security Groups in V3
+ +In V2, security groups which apply to all spaces in a Cloud Foundry deployment are termed “default”, as in “default for running apps” and “default for staging apps”. For example, to apply a default security group to all apps in the running lifecycle, one would PUT /v2/config/running_security_groups/:guid
In V3, security groups which apply to all spaces in a Cloud Foundry deployment are termed “global”, as in “globally-enabled running apps” and “globally-enabled staging apps.” For example, to apply a security group globally to all apps in the running lifecycle, one would PATCH /v3/security_groups/:guid with a body specifying the globally_enabled key. See here for an example.
In V2, on creation, one can specify the spaces to which the security group applies, but not whether it applies globally (by default). To set the group globally to all spaces in the foundation one would PUT /v2/config/running_security_groups/43e0441d-c9c1-4250-b8d5-7fb624379e02.
In V3, on creation, one can both specify the spaces to which it applies and also whether it applies globally (to staging and/or running) by specifying the globally_enabled key. See here for more information.
In V2, the endpoint to apply a security group to a space only includes the lifecycle (“running” or “staging”) explicitly when applying to “staging” (“running” is the default lifecycle). For example, to unbind a security group from the running lifecycle, one would DELETE /v2/security_groups/:guid/spaces/:space_guid, from the staging lifecycle, DELETE /v2/security_groups/:guid/staging_spaces/:space_guid.
In V3, the endpoint to apply a security group to a space includes the lifecycle. For example to unbind a security group from the running lifecycle, one would DELETE /v3/security_groups/:guid/relationships/running_spaces/:space_guid.
Service Brokers in V3
+ +Create, Update and Delete
+ +In V3 these endpoints are now asynchronous. See asynchronous operations and service broker jobs for more information.
+ +Read more about the service broker resource.
+Service Instances in V3
+ +Combining managed and user-provided service instances
+ +In v2, two different endpoints /v2/service_instances and /v2/user_provided_service_instances
+were used to perform operations on service instances according to their types.
In v3, all service instance operations are performed using the service instance resource, regardless of the type.
+Service instances can be of type managed when it is an instantiation of a service offering registered with CF
+or user-provided when it describes an instance of an offering that is not registered with CF.
+The type filter can be used to separately list each type.
The required parameters when creating and updating +a service instance are different for each type as defined in their respective documentation.
+ +Object
+ +The structure of the service instances object as well as some attribute names have changed from V2 to V3. +Each service instance type has type specific fields. Certain fields are omitted when they do not apply to the type of the service instance.
+ +| V2 | +V3 | +
|---|---|
type valid values managed_service_instance and user_provided_service_instance |
+type valid values managed and user-provided |
+
| entity.service_plan_guid | +relationships.service_plan.data.guid | +
| entity.space_guid | +relationships.space.data.guid | +
User provided service instance credentials
+ +The credentials field for user provided service instances is not included in the response object of service_instances.
+/v3/service_instances/:guid/credentials can be used to retrieve the credentials.
Read more about the service instance credential.
+ +Response mode
+ +When operating on service instances of type user-provided the API will respond synchronously for all operations.
When the service instance type is managed the API will respond asynchronously and the operation might include communicating to the service broker. Read more about async responses here.
Listing bindings
+ +In v2, there were specific endpoints /v2/service_instances/:guid/service_bindings, /v2/service_instances/:guid/service_keys
+and /v2/user_provided_service_instances/:guid/service_bindings to retrieve the service bindings and service keys for managed and user-provided service instances.
In v3, the service credential bindings can be filtered by service_instance_guids to retrieve the bindings of any service instance.
Service instance route bindings
+ +In v2, binding a service instance to a route was done as a relationship request for the service instance.
+ +In v3, there is a new resource service route binding that represents a binding between a route and a service instance. +Creation and deletion of route bindings is therefore done via that endpoint in v3.
+ +Audit events for route bindings have changed as follows:
+ +| V2 | +V3 | +
|---|---|
| audit.service_instance.bind_route | +audit.service_route_binding.start_create (async only) audit.service_route_binding.create |
+
| audit.service_instance.unbind_route | +audit.service_route_binding.start_delete (async only) audit.service_route_binding.delete |
+
Read more about the service instance resource.
+Service Bindings in V3
+ +Combining service bindings and service keys
+ +In v2, two different endpoints /v2/service_bindings and /v2/service_keys
+were used to perform bindings operations for service instances.
In v3, all service bindings that are not route bindings are performed using the service credential bindings resource.
+Service credential bindings can be of type app when it is a binding between a service instance and an application
+or key when it only retrieves the credentials of the service instance.
+The type filter can be used to list separately each type.
The required parameters when creating +a service credential binding are different for each type as defined in the documentation.
+ +Object
+ +The structure of the service credential binding object follows V3 pattern.
+If the type is app the object will contain a relationship to the app.
Retrieving service credential bindings details
+ +The credentials, syslog_drain_url and volume_mounts fields for service credential bindings are not included in the response object of service credential bindings.
+/v3/service_credential_bindings/:guid/details can be used to retrieve the credentials.
Read more about the service credential binding details.
+ +Service key operations
+ +In v2, all service keys operations were synchronous.
+ +In v3, all service credential bindings, including those of type key are asynchronous if possible.
Response mode
+ +When operating on service credential bindings of user-provided service instances the API will respond synchronously for all operations.
When operating on service credential bindings of managed service instances the API will respond asynchronously and the operation might include communicating to the service broker. Read more about async responses here.
Audit events
+ +Audit events of type audit.service_key.start_create and audit.service_key.start_delete have been added to track when
+an async create or delete key service credential binding operation has started.
Audit events of type audit.service_binding.update and audit.service_key.update are recorded when metadata update is requested.
Read more about the service credential binding resource.
+Service Offerings in V3
+ +Services resource is now replaced by service offerings resource at /v3/service_offerings
Some services related endpoints nested in other resources have been translated to filters on service_offerings, with the advantage that filters accept multiple values and can be combined.
GET /v2/organizations/:guid/services is now GET /v3/service_offerings?organization_guids=guid.
GET /v2/spaces/:guid/services is now GET /v3/service_offerings?space_guids=guid
GET /v2/services/:guid/service_plans is now a filter on the service plan resource: GET /v3/service_plans?service_offering_guids=guid. This link can also be found in the object’s links section.
In V2, service_broker_name was returned in the response. V3 returns this value only if requested using the fields syntax. Refer to service offerings resource for further information. A link to the Service Broker resource is included in the object’s links section.
The structure of the service offering object as well as some attribute names have changed from V2 to V3:
+ +| V2 | +V3 | +
|---|---|
| label | +name | +
| active | +available | +
| bindable | +broker_catalog.features.bindable | +
| extra | +shareable, broker_catalog.metadata | +
| unique_id | +broker_catalog.id | +
| plan_updateable | +broker_catalog.features.plan_updateable | +
| instances_retrievable | +broker_catalog.features.instances_retrievable | +
| bindings_retrievable | +broker_catalog.features.bindings_retrievable | +
| service_broker_guid | +relationships.service_broker.data.guid | +
Read more about the service offering resource.
+Service Plans in V3
+ +Some service plans related endpoints nested in other resources have been translated to filters on service plans, with the advantage that filters accept multiple values and can be combined.
+ +GET /v2/services/:guid/service_plans -> GET /v3/service_plans?service_offering_guids=guid
Changing plan visibility to Public is not a PUT operation anymore. To change visibility use the service plan visibility resource
The structure of the service plan object as well as some attribute names have changed from V2 to V3:
+ +| V2 | +V3 | +
|---|---|
| active | +available | +
| bindable | +broker_catalog.features.bindable | +
| extra | +broker_catalog.metadata | +
| public | +visibility_type == 'public' (see visibility types) |
+
| unique_id | +broker_catalog.id | +
| plan_updateable | +broker_catalog.features.plan_updateable | +
| service_instances_url | +use service_plan_guids or service_plan_names filter on service instances resource |
+
| service_url | +links.service_offering.href | +
| service_guid | +relationships.service_offering.data.guid | +
Some filters were renamed and changed to accept a list of values:
+ +| V2 | +V3 | +
|---|---|
| service_guid | +service_offering_guids | +
| service_instance_guid | +service_instance_guids | +
| service_broker_guid | +service_broker_guids | +
| unique_id | +broker_catalog_ids | +
Read more about the service plan resource.
+Service Plan Visibility in V3
+ +v2/service_plan_visibilities has been replaced in v3 with a nested resource v3/service_plans/:guid/visibility
This new resource has a type, and can have a list of organizations a space or be of type public
Read more about the service plan visibility resource.
+Space Quotas in V3
+ +In V2, -1 represented an unlimited value for a quota limit.
In V3, null is used to represent an unlimited value.
The names of the limit fields have changed from V2 to V3.
+ +| V2 | +V3 | +
|---|---|
| non_basic_services_allowed | +services.paid_services_allowed | +
| total_services | +services.total_service_instances | +
| total_service_keys | +services.total_service_keys | +
| total_routes | +routes.total_routes | +
| total_reserved_route_ports | +routes.total_reserved_ports | +
| memory_limit | +apps.total_memory_in_mb | +
| instance_memory_limit | +apps.per_process_memory_in_mb | +
| app_instance_limit | +apps.total_instances | +
| app_task_limit | +apps.per_app_tasks | +
Read more about the space quota resource.
+Usage Events in V3
+ +This section covers changes in both app usage events and service usage events.
+ +The V2 service_guid field for service usage events is now renamed to service_offering.guid.
The V2 service_label field for service usage events is now renamed to service_offering.label.
The V2 app_guid field for app usage events is now renamed to process.guid.
The V2 experimental field parent_app_guid for app usage events was used to identify a backing V3 app if present. In V3, this field has been renamed to app.guid and is no longer experimental.
Users and Roles in V3
+ +The user resource remains largely unchanged from the v2 API. On v2, GET /v2/users was restricted to admins, and other users needed to use nested endpoints (GET /v2/organizations/:guid/user and GET /v2/spaces/:guid/user) to view user resources. On v3, those nested endpoints are carried over, but GET /v3/users is now available for all users in a similar way to other resources. Note that this does not change what user resources are visible.
In v2, roles were modeled as associations between organization and space endpoints. In V3, roles have a dedicated resource: /v3/roles. This has changed the manner in which roles are assigned. For example, in V2, to assign a user the org_manager role, one would PUT /v2/organizations/:org_guid/managers/:user_id. In V3, one would POST /v3/roles with the role type and relationships to the user and organization.
In v2, when an Org Manager gives a person an Org or Space role, that person automatically receives Org User status in that org. This is no longer the case in the v3 API.
+ +Read more about users and roles.
+Deprecated Endpoints
+ +The specialized /v2/apps/:guid/restage endpoint is replaced by the
+builds resource. Builds allow finer-grained control and increased
+flexibility when staging packages into droplets. The V3 API avoids making
+assumptions about which package/droplet to use when staging or running an app
+and thus leaves it up to clients.
Restage
+ +The specialized /v2/apps/:guid/restage endpoint is replaced by the builds resource. Builds allow finer-grained
+control and increased flexibility when staging packages into droplets. The V3 API avoids making assumptions about which
+package/droplet to use when staging or running an app and thus leaves it up to clients.
Replicating Restage
+ +-
+
Get newest READY package for an app:
+ ++GET /v3/packages?app_guids=:app-guid&order_by=-created_at&states=READY +
+Stage the package:
+ ++POST /v3/build +
+Poll build until the state is
+ +STAGED:+GET /v3/builds/build-guid +
+Stop the app:
+ ++POST /v3/apps/:guid/actions/stop +
+Set the app’s current droplet to the build’s resulting droplet:
+ ++PATCH /v3/apps/:guid/relationships/current_droplet +
+Start app:
+ ++POST /v3/apps/:guid/actions/start +
+
For a zero-downtime restage, you may wish to use deployments instead of stopping and starting the app.
+ +Restage Event
+ +Since the V3 API has no concept of a “restage”, the audit.app.restage audit
+event is no longer reported. Instead, the following events can be tracked:
| Audit Event | +Description | +
|---|---|
| audit.build.create | +A build is created (staging is initiated) | +
| audit.droplet.create | +A droplet is created (staging finishes successfully) | +
| audit.app.stop | +Stopping an app is initiated | +
| audit.app.droplet.mapped | +A droplet is set as the current droplet for an app | +
| audit.app.start | +Starting an app is initiated | +
| audit.app.deployment.create | +A deployment is initialized | +