API docs by Redocly

Cloud Foundry V3 API (alpha-0.1.1)

Download OpenAPI specification:

URL: https://www.cloudfoundry.org/ License: Apache 2.0

Welcome to the Experimental Cloud Foundry V3 API Docs!

Expermiental Warning

This OpenAPI specification is a experiment and not ready for productive use.

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 deprecated but still available for interacting with Cloud Foundry.
  • Running Tasks
  • V3 API Documentation OpenAPI Spec Source Code.

Admin

Administrative operations for Cloud Foundry platform management.

Clear the buildpack cache

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.

Authorizations:
oauth

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Apps

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

List apps

Retrieve all apps the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of app GUIDs to filter by

names
Array of strings

Comma-delimited list of app names to filter by

space_guids
Array of strings

Comma-delimited list of space GUIDs to filter by

organization_guids
Array of strings

Comma-delimited list of organization GUIDs to filter by

stacks
Array of strings

Comma-delimited list of stack names to filter by

lifecycle_type
string
Enum: "buildpack" "cnb" "docker"

Lifecycle type to filter by

include
Array of strings
Items Enum: "space" "space.organization"

Optionally include a list of unique related resources in the response

Responses

Response samples

Content type
application/json
{}

Create an app

Creates a new app.

Authorizations:
oauth
Request Body schema: application/json
required

App object that needs to be created

name
required
string

Name of the app

object

Environment variables to be used for the App when running

object (Lifecycle)

Provides the lifecycle object for the application

required
object
object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "my_app",
  • "relationships": {
    }
}

Response samples

Content type
application/json
{}

Get an app

Retrieve a specific app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
include
Array of strings
Items Enum: "space" "space.organization"

Optionally include a list of unique related resources in the response

Responses

Response samples

Content type
application/json
{}

Update an app

Update an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

App object that needs to be updated

name
string

Name of the app

object

Environment variables to be used for the App when running

object (Lifecycle)

Lifecycle to be used when updating the app; note data is a required field in lifecycle if lifecycle is updated. type may NOT be changed from its current value.

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "my_app",
  • "lifecycle": {
    }
}

Response samples

Content type
application/json
{}

Delete an app

Delete an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Start an app

Start an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Stop an app

Stop an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Restart an app

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

List droplets for an app

Retrieve all droplets belonging to an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of droplet guids to filter by

states
Array of strings
Items Enum: "AWAITING_UPLOAD" "PROCESSING_UPLOAD" "STAGED" "COPYING" "FAILED" "EXPIRED"

Comma-delimited list of droplet states to filter by

Responses

Response samples

Content type
application/json
{}

Get current droplet

Get the current droplet for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Get current droplet association for an app

This endpoint retrieves the current droplet relationship for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Set current droplet

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Droplet relationship object that needs to be set

required
object (Relationship)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{}

Clear buildpack cache for application

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get environment for an app

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "staging_env_json": {},
  • "running_env_json": {},
  • "environment_variables": {
    },
  • "system_env_json": {
    },
  • "application_env_json": {
    }
}

Get environment variables for an app

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Update environment variables for an app

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. The updated environment variables will not take effect until the app is restarted.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for update environment variables for an app.

object

Environment variables to inject; keys and values must be strings

Responses

Request samples

Content type
application/json
{
  • "var": {
    }
}

Response samples

Content type
application/json
{}

List app features

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get an app feature

Get an app feature.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

name
required
string
Enum: "ssh" "revisions" "service-binding-k8s" "file-based-vcap-services"

Name of the feature.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Update an app feature

Update an app feature.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

name
required
string
Enum: "ssh" "revisions" "service-binding-k8s" "file-based-vcap-services"

Name of the feature.

Request Body schema: application/json

Request body for update an app feature.

enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": false
}

Response samples

Content type
{
  • "errors": [
    ]
}

Get permissions for an app

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "read_basic_data": true,
  • "read_sensitive_data": false
}

Get SSH enabled for an app

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "enabled": false,
  • "reason": "Disabled globally"
}

App Usage Events

App usage events are a record of changes in the usage of apps and tasks.

List app usage events

Retrieve all app usage events.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

after_guid
string

Filters out events before and including the event with the given guid

guids
Array of strings

Comma-delimited list of usage event guids to filter by

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get an app usage event

Retrieve a specific app usage event.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2020-05-28T16:41:23Z",
  • "updated_at": "2020-05-28T16:41:26Z",
  • "state": {
    },
  • "app": {
    },
  • "process": {
    },
  • "space": {
    },
  • "organization": {
    },
  • "buildpack": {
    },
  • "task": {
    },
  • "memory_in_mb_per_instance": {
    },
  • "instance_count": {
    },
  • "links": {}
}

Purge and seed app usage events

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.

Authorizations:
oauth

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

Audit Events

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

List audit events

Retrieve all audit events the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

types
Array of strings
Items Enum: "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" "audit.organization.create" "audit.organization.delete-request" "audit.organization.update" "audit.route.create" "audit.route.delete-request" "audit.route.share" "audit.route.transfer-owner" "audit.route.unshare" "audit.route.update" "audit.service.create" "audit.service.delete" "audit.service.update" "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" "audit.service_broker.create" "audit.service_broker.delete" "audit.service_broker.update" "audit.service_dashboard_client.create" "audit.service_dashboard_client.delete" "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" "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" "audit.service_plan.create" "audit.service_plan.delete" "audit.service_plan.update" "audit.service_plan_visibility.create" "audit.service_plan_visibility.delete" "audit.service_plan_visibility.update" "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" "audit.space.create" "audit.space.delete-request" "audit.space.update" "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" "audit.user_provided_service_instance.create" "audit.user_provided_service_instance.delete" "audit.user_provided_service_instance.show" "audit.user_provided_service_instance.update" "app.crash" "blob.remove_orphan"

Comma-delimited list of event types to filter by

target_guids
Array of strings

Comma-delimited list of target guids to filter by. Also supports filtering by exclusion.

space_guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "resources": [
    ]
}

Get an audit event

Retrieve a specific audit event.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2016-06-08T16:41:23Z",
  • "updated_at": "2016-06-08T16:41:26Z",
  • "type": "audit.app.update",
  • "actor": {
    },
  • "target": {
    },
  • "data": {
    },
  • "space": {
    },
  • "organization": {
    },
  • "links": {}
}

Builds

Builds represent the process of staging an application package.

List builds

Retrieve all builds.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

states
Array of strings
Items Enum: "STAGING" "STAGED" "FAILED"

Comma-delimited list of build states to filter by

app_guids
Array of strings

Comma-delimited list of app GUIDs to filter by

package_guids
Array of strings

Comma-delimited list of package GUIDs to filter by

Responses

Response samples

Content type
application/json
{}

Create a build

Create a build.

Authorizations:
oauth
Request Body schema: application/json
required

Build object that needs to be created

required
object (Relationship)
object (Lifecycle)

The lifecycle type defines how the application droplet is created and run. The following lifecycle types are supported: - buildpack: Traditional buildpacks for Cloud Foundry applications. - cnb: Cloud Native Buildpacks that are OCI-compliant. - docker: Run pre-built Docker images.

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

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "package": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "state": "STAGING",
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "error": "string",
  • "lifecycle": {
    },
  • "checksum": {
    },
  • "metadata": {
    },
  • "relationships": { },
  • "package": {
    },
  • "droplet": {
    },
  • "created_by": {
    },
  • "links": {
    }
}

Get a build

Retrieve a build.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "state": "STAGING",
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "error": "string",
  • "lifecycle": {
    },
  • "checksum": {
    },
  • "metadata": {
    },
  • "relationships": { },
  • "package": {
    },
  • "droplet": {
    },
  • "created_by": {
    },
  • "links": {
    }
}

Update a build

Update a build.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for update a build.

state
string
Enum: "STAGING" "STAGED" "FAILED"

State of the build

staging_memory_in_mb
integer or null

Memory in MB allocated for staging of the build

staging_disk_in_mb
integer or null

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

A string describing errors during the build process

object (Lifecycle)

Provides the lifecycle object to use during staging

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "state": "STAGING",
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "error": "string",
  • "lifecycle": {
    },
  • "checksum": {
    },
  • "metadata": {
    },
  • "relationships": { },
  • "package": {
    },
  • "droplet": {
    },
  • "created_by": {
    },
  • "links": {
    }
}

List builds for an app

Retrieve all builds for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

states
Array of strings
Items Enum: "STAGING" "STAGED" "FAILED"

Comma-delimited list of build states to filter by

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{}

Update a build

Update a build.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Build object that needs to be updated

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "state": "STAGING",
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "error": "string",
  • "lifecycle": {
    },
  • "checksum": {
    },
  • "metadata": {
    },
  • "relationships": { },
  • "package": {
    },
  • "droplet": {
    },
  • "created_by": {
    },
  • "links": {
    }
}

Buildpacks

Buildpacks are used during a build to download external dependencies and transform a package into an executable droplet.

List buildpacks

Retrieve all buildpacks.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

names
Array of strings

Comma-delimited list of buildpack names to filter by

stacks
Array of strings

Comma-delimited list of stacks to filter by

Responses

Response samples

Content type
application/json
{}

Create a buildpack

Create a buildpack.

Authorizations:
oauth
Request Body schema: application/json
required

Buildpack object that needs to be added

name
required
string

The 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

lifecycle
string

The version of buildpack the buildpack will use. buildpack indicates Classic Buildpacks. cnb indicates Cloud Native Buildpacks

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

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "ruby_buildpack",
  • "position": 42,
  • "enabled": true,
  • "locked": false,
  • "stack": "windows64"
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "state": "AWAITING_UPLOAD",
  • "stack": "string",
  • "lifecycle": "string",
  • "position": 0,
  • "enabled": true,
  • "locked": true,
  • "filename": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Get a buildpack

Retrieve a buildpack.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "state": "AWAITING_UPLOAD",
  • "stack": "string",
  • "lifecycle": "string",
  • "position": 0,
  • "enabled": true,
  • "locked": true,
  • "filename": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Update a buildpack

Update a buildpack.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Buildpack object that needs to be updated

name
string

The name of the buildpack

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

stack
string

The name of the stack that the buildpack will use

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "ruby_buildpack",
  • "position": 42,
  • "enabled": true,
  • "locked": false,
  • "stack": "windows64"
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "state": "AWAITING_UPLOAD",
  • "stack": "string",
  • "lifecycle": "string",
  • "position": 0,
  • "enabled": true,
  • "locked": true,
  • "filename": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Delete a buildpack

Delete a buildpack.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Upload buildpack bits

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: multipart/form-data
required

The buildpack file to be uploaded

bits
string <binary>
Array of objects

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "state": "AWAITING_UPLOAD",
  • "stack": "string",
  • "lifecycle": "string",
  • "position": 0,
  • "enabled": true,
  • "locked": true,
  • "filename": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Deployments

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

List deployments

Retrieve all deployments.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

app_guids
Array of strings

Comma-delimited list of app GUIDs to filter by

states
Array of strings

Comma-delimited list of states to filter by

status_reasons
Array of strings
Items Enum: "DEPLOYING" "PAUSED" "CANCELING" "DEPLOYED" "CANCELED" "SUPERSEDED"

Comma-delimited list of status reasons to filter by

status_values
Array of strings
Items Enum: "ACTIVE" "FINALIZED"

Comma-delimited list of status values to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "resources": [
    ]
}

Create a deployment

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.

Authorizations:
oauth
Request Body schema: application/json
required

Deployment object that needs to be created

relationships
object (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.

strategy
string
Enum: "rolling" "canary"
object
object (Relationship)
object (Relationship)
object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "revision": {
    },
  • "strategy": "rolling",
  • "relationships": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "strategy": "rolling",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Get a deployment

Retrieve a deployment.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "strategy": "rolling",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Update a deployment

Update a deployment.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Deployment object that needs to be updated

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "strategy": "rolling",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Cancel a deployment

Cancel a deployment.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "strategy": "rolling",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Continue a deployment

Continue a deployment.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "strategy": "rolling",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Domains

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

List domains

Retrieve all domains the user has access to.

Permitted roles: All Roles

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Enum: "created_at" "-created_at" "updated_at" "-updated_at"

Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of guids to filter by

names
Array of strings

Comma-delimited list of domain names to filter by (case-insensitive)

organization_guids
Array of strings

Comma-delimited list of owning organization guids to filter by

Responses

Response samples

Content type
application/json
{}

Create a domain

Create a domain.

Permitted roles: Admin, Org Manager (when an organization relationship is provided)

Authorizations:
oauth
Request Body schema: application/json
required

Domain object that needs to be created

name
required
string

Name of the domain; must be unique (case-insensitive)

internal
boolean
Default: false

Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic

object

The desired router group. note: creates a tcp domain; cannot be used when internal is set to true or domain is scoped to an org

enforce_route_policies
boolean
Default: false

When true, GoRouter enforces route policies for routes on this domain using mutual TLS (mTLS). Set at creation only; cannot be changed on update. Cannot be used with internal domains

route_policies_scope
string
Enum: "any" "org" "space"

Operator-defined boundary for allowed callers: any, org, or space. Required when enforce_route_policies is true. Set at creation only; cannot be changed on update

object

Relationships to the organization the domain will be scoped to and the organizations the domain will be shared with

object (Metadata)

Labels and annotations applied to the domain

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example.com",
  • "internal": false
}

Response samples

Content type
application/json
{}

Get a domain

Retrieve a domain.

Permitted roles: 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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Update a domain

Update a domain.

Permitted roles: Admin, Org Manager (if domain is scoped to organization managed by the org manager)

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Domain object that needs to be updated

object (Metadata)

Labels and annotations applied to the domain

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

Delete a domain

Delete a domain.

Permitted roles: Admin, Org Manager (if domain is scoped to organization managed by the org manager)

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Share a domain

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.

Permitted roles: Admin, Org Manager

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

The organization guids with which to share the domain

required
Array of objects (Relationship)

The organization guids with which to share the domain

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Unshare a domain

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.

Permitted roles: Admin, Org Manager (can be in either the domain's owning organization or the organization it has been shared to)

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

org_guid
required
string <uuid>

The guid of the organization to unshare the domain from

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Check reserved routes for a domain

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.

Permitted roles: 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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

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

Responses

Response samples

Content type
application/json
{
  • "matching_route": true
}

List domains for an organization

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.

Permitted roles: All Roles

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The guid of the organization

query Parameters
guids
Array of strings

Comma-delimited list of guids to filter by

names
Array of strings

Comma-delimited list of domain names to filter by (case-insensitive)

organization_guids
Array of strings

Comma-delimited list of owning organization guids to filter by

page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Enum: "created_at" "-created_at" "updated_at" "-updated_at"

Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{}

Droplets

Droplets are the result of staging an application package.

List droplets for an app

Retrieve all droplets belonging to an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of droplet guids to filter by

states
Array of strings
Items Enum: "AWAITING_UPLOAD" "PROCESSING_UPLOAD" "STAGED" "COPYING" "FAILED" "EXPIRED"

Comma-delimited list of droplet states to filter by

Responses

Response samples

Content type
application/json
{}

List droplets

Retrieve all droplets.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of droplet GUIDs to filter by

states
Array of strings
Items Enum: "AWAITING_UPLOAD" "PROCESSING_UPLOAD" "STAGED" "COPYING" "FAILED" "EXPIRED"

Comma-delimited list of droplet states to filter by

app_guids
Array of strings

Comma-delimited list of app GUIDs to filter by

current
boolean

If true, only include the current droplet for each app

space_guids
Array of strings

Comma-delimited list of space GUIDs to filter by

organization_guids
Array of strings

Comma-delimited list of organization GUIDs to filter by

Responses

Response samples

Content type
application/json
{}

Create a droplet

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

Authorizations:
oauth
Request Body schema: application/json
required

Droplet object that needs to be created

required
object
process_types
object

Process names and start commands for the droplet

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "relationships": {
    },
  • "process_types": {
    }
}

Response samples

Content type
application/json
{}

Get a droplet

Retrieve a droplet.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Update a droplet

Update a droplet.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Droplet object that needs to be updated

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

image
string

Image reference where the built complete image was stored

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "state": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "links": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

Delete a droplet

Delete a droplet.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "operation": "string",
  • "state": "PROCESSING",
  • "errors": [
    ],
  • "warnings": [
    ],
  • "links": {
    }
}

Download droplet bits

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Upload droplet bits

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema:
required

The droplet file to be uploaded

bits
string <binary>
Array of objects

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "state": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "links": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

List droplets for a package

Retrieve a list of droplets belonging to a package.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of droplet guids to filter by

states
Array of strings

Comma-delimited list of droplet states to filter by

Responses

Response samples

Content type
application/json
{}

Environment Variable Groups

There are two types of environment variable groups: running and staging.

Get an environment variable group

Retrieve an environment variable group.

Authorizations:
oauth
path Parameters
name
required
string
Enum: "running" "staging"

Name of the environment variable group.

Responses

Response samples

Content type
application/json
{}

Update environment variable group

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.

Variables updated in the running environment variable group will not take effect until apps are restarted.

Authorizations:
oauth
path Parameters
name
required
string
Enum: "running" "staging"

Name of the environment variable group.

Request Body schema: application/json
required

The environment variables to update

object

Environment variables to inject; keys and values must be strings

Responses

Request samples

Content type
application/json
{
  • "var": {
    }
}

Response samples

Content type
application/json
{}

Feature Flags

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

List feature flags

Retrieve all feature_flags.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

Responses

Response samples

Content type
application/json
{}

Get a feature flag

Get a feature flag.

Authorizations:
oauth
path Parameters
name
required
string
Enum: "app_bits_upload" "app_scaling" "diego_docker" "diego_cnb" "env_var_visibility" "hide_marketplace_from_unauthenticated_users" "private_domain_creation" "resource_matching" "route_creation" "route_sharing" "service_instance_creation" "service_instance_sharing" "set_roles_by_username" "space_developer_env_var_visibility" "space_scoped_private_broker_creation" "task_creation" "unset_roles_by_username" "user_org_creation"

The name of the feature flag

Responses

Response samples

Content type
application/json
{}

Update a feature flag

Update a feature flag.

Authorizations:
oauth
path Parameters
name
required
string
Enum: "app_bits_upload" "app_scaling" "diego_docker" "diego_cnb" "env_var_visibility" "hide_marketplace_from_unauthenticated_users" "private_domain_creation" "resource_matching" "route_creation" "route_sharing" "service_instance_creation" "service_instance_sharing" "set_roles_by_username" "space_developer_env_var_visibility" "space_scoped_private_broker_creation" "task_creation" "unset_roles_by_username" "user_org_creation"

The name of the feature flag

Request Body schema: application/json
required

Feature flag object that needs to be updated

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

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "custom_error_message": "error message the user sees"
}

Response samples

Content type
application/json
{}

Info

Info endpoints expose Cloud Controller configuration information.

Get platform info

Get information about the platform.

Responses

Response samples

Content type
application/json
{
  • "build": "",
  • "cli_version": {
    },
  • "custom": { },
  • "description": "",
  • "name": "",
  • "version": 0,
  • "osbapi_version": "",
  • "rate_limits": {
    },
  • "links": {}
}

Get platform usage summary

This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation.

Authorizations:
oauth

Responses

Response samples

Content type
application/json
{
  • "usage_summary": {
    },
  • "links": {}
}

Internal

Internal endpoints for system monitoring and metrics.

Isolation Segments

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

List isolation segments

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.

Permitted roles: All Roles

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Enum: "created_at" "-created_at" "updated_at" "-updated_at" "name" "-name"

Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and name

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of isolation segment guids to filter by

names
Array of strings

Comma-delimited list of isolation segment names to filter by (case-insensitive)

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

Responses

Response samples

Content type
application/json
{}

Create an isolation segment

Create an isolation segment.

Permitted roles: Admin

Authorizations:
oauth
Request Body schema: application/json
required

Isolation segment to create

name
required
string

Name of the isolation segment; must be unique (case-insensitive)

object (Metadata)

Labels and annotations applied to the isolation segment

Responses

Request samples

Content type
application/json
{
  • "name": "my_segment"
}

Response samples

Content type
application/json
{}

Get an isolation segment

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.

Permitted roles: All Roles

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Update an isolation segment

Update an isolation segment.

Permitted roles: Admin

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Isolation segment to update

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

object (Metadata)

Labels and annotations applied to the isolation segment

Responses

Request samples

Content type
application/json
{
  • "name": "my_isolation_segment"
}

Response samples

Content type
application/json
{}

Delete an isolation segment

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

Permitted roles: Admin

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Entitle organizations for an isolation segment

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.

Permitted roles: Admin

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Organization relationships; each organization will be entitled to manage this isolation segment

Array of objects (Relationship)
object

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{}

List organizations relationship

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.

Permitted roles: All Roles

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Revoke entitlement to isolation segment for an organization

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.

Permitted roles: Admin

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

org_guid
required
string <uuid>

The guid of the organization to revoke entitlement from

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List spaces relationship

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.

Permitted roles: All Roles

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

List organizations for isolation segment

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

Permitted roles: Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Billing Manager, Org Manager

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
names
Array of strings

Comma-delimited list of organization names to filter by (case-insensitive)

guids
Array of strings

Comma-delimited list of organization guids to filter by

page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Enum: "created_at" "-created_at" "updated_at" "-updated_at" "name" "-name"

Value to sort by; defaults to ascending. Prepend with - to sort descending. Valid values are created_at, updated_at, and name

Responses

Response samples

Content type
application/json
{}

Jobs

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

Get a job

Retrieve a specific job.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Manifests

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

Generate a manifest for an app

Generate a manifest for an app and its underlying processes.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

Organizations

An org is a development account that an individual or multiple collaborators can own and use.

List organizations

Retrieve all organizations the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

names
Array of strings

Comma-delimited list of organization names to filter by

guids
Array of strings

Comma-delimited list of organization guids to filter by

Responses

Response samples

Content type
application/json
{}

Create an organization

Create an organization.

Authorizations:
oauth
Request Body schema: application/json
required

Organization object that needs to be created

name
required
string

Organization name

suspended
boolean

Whether an organization is suspended or not

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "my-organization"
}

Response samples

Content type
application/json
{}

Get an organization

This endpoint retrieves the specified organization object.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Update an organization

Update an organization.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Organization object that needs to be updated

name
string

Organization name

suspended
boolean

Whether an organization is suspended or not

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "my-organization"
}

Response samples

Content type
application/json
{}

Delete an organization

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get default domain

Retrieve the default domain for a given organization.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "internal": true,
  • "router_group": {
    },
  • "supported_protocols": [
    ],
  • "enforce_route_policies": true,
  • "route_policies_scope": "any",
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Get usage summary

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

List users for an organization

Retrieve all users with a role in the specified organization.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

guids
Array of strings

Comma-delimited list of user guids to filter by

usernames
Array of strings

Comma-delimited list of usernames to filter by

origins
Array of strings

Comma-delimited list of user origins to filter by

partial_usernames
Array of strings

Comma-delimited list of partial usernames to filter by

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get default isolation segment

Retrieve the default isolation segment for a given organization.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Assign default isolation segment

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.

Apps will not run in the new default isolation segment until they are restarted.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for assign default isolation segment.

Relationship (object) or null
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{}

Organization Quotas

Organization quotas are named sets of memory, log rate, service, and instance usage quotas.

List organization quotas

This endpoint lists all organization quota resources.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

guids
Array of strings

Comma-delimited list of organization quota guids to filter by

names
Array of strings

Comma-delimited list of organization quota names to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "resources": [
    ]
}

Create an organization quota

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.

Authorizations:
oauth
Request Body schema: application/json
required

Organization quota object that needs to be created

name
required
string

Name of the quota

object

Quotas that affect applications and application sub-resources

object

Quotas that affect services

object

Quotas that affect routes

object

Quotas that affect domains

object
object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "production"
}

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2016-05-04T17:00:41Z",
  • "updated_at": "2016-05-04T17:00:41Z",
  • "name": "don-quixote",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "domains": {
    },
  • "relationships": {
    },
  • "links": {}
}

Get an organization quota

This endpoint gets an individual organization quota resource.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2016-05-04T17:00:41Z",
  • "updated_at": "2016-05-04T17:00:41Z",
  • "name": "don-quixote",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "domains": {
    },
  • "relationships": {
    },
  • "links": {}
}

Update an organization quota

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Organization quota object that needs to be updated

name
string

Name of the quota

object

Quotas that affect applications and application sub-resources

object

Quotas that affect services

object

Quotas that affect routes

object

Quotas that affect domains

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "domains": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2016-05-04T17:00:41Z",
  • "updated_at": "2016-05-04T17:00:41Z",
  • "name": "don-quixote",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "domains": {
    },
  • "relationships": {
    },
  • "links": {}
}

Delete an organization quota

Organization quotas cannot be deleted when applied to any organizations.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Apply an organization quota to an organization

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

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

Authorizations:
oauth
path Parameters
quota_guid
required
string <uuid>

GUID of the quota.

Request Body schema: application/json

Request body for apply an organization quota to an organization.

Array of objects (Relationship)
object

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{}

Packages

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

List packages

Retrieve all packages.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of package guids to filter by

states
Array of strings
Items Enum: "AWAITING_UPLOAD" "PROCESSING_UPLOAD" "READY" "FAILED" "COPYING" "EXPIRED"

Comma-delimited list of package states to filter by

types
Array of strings
Items Enum: "bits" "docker"

Comma-delimited list of package types to filter by

app_guids
Array of strings

Comma-delimited list of app guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

Responses

Response samples

Content type
application/json
{}

Create a package

Create a package.

Authorizations:
oauth
Request Body schema: application/json
required

Package object that needs to be created or copied. When copying (source_guid query parameter is provided), only relationships.app is required. When creating a new package, type and relationships.app are required.

type
string
Enum: "bits" "docker"

Type of the package; valid values are bits or docker. Required when creating a new package (when source_guid is not provided). Not required when copying a package (when source_guid is provided).

object

Data for package type

required
object
object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "bits",
  • "relationships": {
    }
}

Response samples

Content type
application/json
{}

Get a package

Retrieve a package.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "bits",
  • "data": {
    },
  • "state": "AWAITING_UPLOAD",
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Update a package

Update a package.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Package object that needs to be updated

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

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.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "bits",
  • "data": {
    },
  • "state": "AWAITING_UPLOAD",
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Delete a package

Delete a package.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List droplets for a package

Retrieve a list of droplets belonging to a package.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of droplet guids to filter by

states
Array of strings

Comma-delimited list of droplet states to filter by

Responses

Response samples

Content type
application/json
{}

List packages for an app

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
guids
Array of strings

Comma-delimited list of app GUIDs to filter by

page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

states
Array of strings
Items Enum: "AWAITING_UPLOAD" "PROCESSING_UPLOAD" "READY" "FAILED" "COPYING" "EXPIRED"

Comma-delimited list of package states to filter by

types
Array of strings
Items Enum: "bits" "docker"

Comma-delimited list of package types to filter by

Responses

Response samples

Content type
application/json
{}

Upload package bits

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema:

Request body for upload package bits.

bits
string <binary>
Array of objects

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "bits",
  • "data": {
    },
  • "state": "AWAITING_UPLOAD",
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Download package bits

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Processes

Processes define the runnable units of an app.

List processes

Retrieve all processes.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of process guids to filter by

types
Array of strings

Comma-delimited list of process types to filter by

app_guids
Array of strings

Comma-delimited list of app guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

Responses

Response samples

Content type
application/json
{
  • "total_results": 0,
  • "total_pages": 0,
  • "first": {
    },
  • "last": {
    },
  • "next": {
    },
  • "previous": {
    },
  • "resources": [
    ]
}

Get a process

Get a process.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Update a process

Update a process.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Process object that needs to be updated

command
string or null

The command used to start the process; use null to revert to the buildpack-detected or procfile-provided start command

object (HealthCheck)

The health check to perform on the process

object (HealthCheck)

The readiness health check to perform on the process

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "command": "rackup",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": "8b898373-21c7-4028-b85f-cc5068e68df9",
  • "type": "string",
  • "command": "string",
  • "user": "string",
  • "instances": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "log_rate_limit_in_bytes_per_second": 0,
  • "health_check": {
    },
  • "readiness_health_check": {
    },
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

List instances for a process

Retrieve the instances for a process. Unlike the stats endpoint, this returns a simplified view with only the index, state, and uptime of each instance.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Get stats for a process

Get stats for a process.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "resources": [
    ]
}

Scale a process

Scale a process.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for scale a process.

instances
integer or null

The number of instances to run

memory_in_mb
integer or null

The memory in MB allocated per instance

disk_in_mb
integer or null

The disk in MB allocated per instance

log_rate_limit_in_bytes_per_second
integer or null

The log rate limit in bytes per second per instance

Responses

Request samples

Content type
application/json
{
  • "instances": 5,
  • "memory_in_mb": 256,
  • "disk_in_mb": 1024,
  • "log_rate_limit_in_bytes_per_second": 1024
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": "8b898373-21c7-4028-b85f-cc5068e68df9",
  • "type": "string",
  • "command": "string",
  • "user": "string",
  • "instances": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "log_rate_limit_in_bytes_per_second": 0,
  • "health_check": {
    },
  • "readiness_health_check": {
    },
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Terminate a process instance

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

index
required
integer

Zero-based index of the process instance.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List processes for an app

Retrieves all processes belonging to an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

Responses

Response samples

Content type
application/json
{
  • "total_results": 0,
  • "total_pages": 0,
  • "first": {
    },
  • "last": {
    },
  • "next": {
    },
  • "previous": {
    },
  • "resources": [
    ]
}

Get a process for an app

Get a specific process for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

Process type, such as web or worker.

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": "8b898373-21c7-4028-b85f-cc5068e68df9",
  • "type": "string",
  • "command": "string",
  • "user": "string",
  • "instances": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "log_rate_limit_in_bytes_per_second": 0,
  • "health_check": {
    },
  • "readiness_health_check": {
    },
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Update a process for an app

Update a specific process for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

Process type, such as web or worker.

Request Body schema: application/json
required

Process object that needs to be updated

command
string or null

The command used to start the process; use null to revert to the buildpack-detected or procfile-provided start command

object (HealthCheck)

The health check to perform on the process

object (HealthCheck)

The readiness health check to perform on the process

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "command": "rackup",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": "8b898373-21c7-4028-b85f-cc5068e68df9",
  • "type": "string",
  • "command": "string",
  • "user": "string",
  • "instances": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "log_rate_limit_in_bytes_per_second": 0,
  • "health_check": {
    },
  • "readiness_health_check": {
    },
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Get stats for a process for an app

Get stats for a specific process for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

Process type, such as web or worker.

Responses

Response samples

Content type
application/json
{
  • "resources": [
    ]
}

Scale a process for an app

Scale a specific process for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

Process type, such as web or worker.

Request Body schema: application/json

Request body for scale a process for an app.

instances
integer or null

The number of instances to run

memory_in_mb
integer or null

The memory in MB allocated per instance

disk_in_mb
integer or null

The disk in MB allocated per instance

log_rate_limit_in_bytes_per_second
integer or null

The log rate limit in bytes per second per instance

Responses

Request samples

Content type
application/json
{
  • "instances": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "log_rate_limit_in_bytes_per_second": 0
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": "8b898373-21c7-4028-b85f-cc5068e68df9",
  • "type": "string",
  • "command": "string",
  • "user": "string",
  • "instances": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "log_rate_limit_in_bytes_per_second": 0,
  • "health_check": {
    },
  • "readiness_health_check": {
    },
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Terminate a process instance for an app

Terminate a specific process instance for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

Process type, such as web or worker.

index
required
integer

Zero-based index of the process instance.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Resource Matches

Resource Matches are used to determine if a resource has been previously uploaded to the Cloud Controller.

Create a resource match

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

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.

Authorizations:
oauth
Request Body schema: application/json

Request body for create a resource match.

required
Array of objects

List of resources to check for in the resource cache

Responses

Request samples

Content type
application/json
{
  • "resources": [
    ]
}

Response samples

Content type
application/json
{
  • "resources": [
    ]
}

Revisions

Revisions represent code used by an application at a specific time.

Get a revision

Retrieve a revision.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 0,
  • "description": "string",
  • "droplet": {
    },
  • "relationships": {
    },
  • "enabled": true,
  • "metadata": {
    },
  • "links": {
    }
}

Update a revision

Update a revision.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Revision object that needs to be updated

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version": 0,
  • "description": "string",
  • "droplet": {
    },
  • "relationships": {
    },
  • "enabled": true,
  • "metadata": {
    },
  • "links": {
    }
}

Get environment variables for a revision

Retrieve the environment variables that are associated with the revision.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

List revisions for an app

Retrieve revisions for an app the user has access to.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

versions
Array of strings

Comma-delimited list of revision versions to filter by

Responses

Response samples

Content type
application/json
{}

List deployed revisions for an app

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

Responses

Response samples

Content type
application/json
{}

Roles

Roles are used to control access to resources.

List roles

This endpoint lists roles that the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of role guids to filter by

types
Array of strings
Items Enum: "organization_user" "organization_auditor" "organization_manager" "organization_billing_manager" "space_auditor" "space_developer" "space_manager" "space_supporter"

Comma-delimited list of role types to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

user_guids
Array of strings

Comma-delimited list of user guids to filter by

include
Array of strings
Items Enum: "user" "space" "organization"

Optionally include additional related resources in the response; valid values are user, space, and organization.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ],
  • "included": {
    }
}

Create a role

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.

If CAPI property cc.allow_user_creation_by_org_manager is enabled, the organization role is being created by username + origin and the user does not exist in UAA yet, the user will be created. The origin must be different from uaa in this case.

Authorizations:
oauth
Request Body schema: application/json

Role to create

type
string
Enum: "organization_user" "organization_auditor" "organization_manager" "organization_billing_manager" "space_auditor" "space_developer" "space_manager" "space_supporter"

Role to create

object

Responses

Request samples

Content type
application/json
Example
{
  • "type": "organization_auditor",
  • "relationships": {
    }
}

Response samples

Content type
application/json
Example
{}

Get a role

This endpoint gets an individual role resource.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
include
Array of strings
Items Enum: "user" "space" "organization"

Optionally include additional related resources in the response; valid values are user, space, and organization.

Responses

Response samples

Content type
application/json
{}

Delete a role

This endpoint deletes an individual role.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Root

Root API endpoints that provide entry points and API information.

Global API Root

This endpoint returns links to the APIs available on a given Cloud Foundry deployment.

Responses

Response samples

Content type
application/json
{}

Get V3 API root

Returns the V3 API root endpoint information.

Responses

Response samples

Content type
application/json
{
  • "links": {
    }
}

Routes

Routes are used to map a URL to an app.

List routes

Retrieve all routes the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

protocols
Array of strings
Items Enum: "http" "tcp"

Comma-delimited list of protocols to filter by

hosts
Array of strings

Comma-delimited list of hosts to filter by

paths
Array of strings

Comma-delimited list of paths to filter by

ports
Array of integers

Comma-delimited list of ports to filter by

domain_guids
Array of strings

Comma-delimited list of domain GUIDs to filter by

space_guids
Array of strings

Comma-delimited list of space GUIDs to filter by

app_guids
Array of strings

Comma-delimited list of app GUIDs to filter by

organization_guids
Array of strings

Comma-delimited list of organization GUIDs to filter by

service_instance_guids
Array of strings

Comma-delimited list of service instance GUIDs to filter by

include
Array of strings
Items Enum: "domain" "space.organization" "space"

Optionally include a list of unique related resources in the response

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a route

Create a route.

Authorizations:
oauth
Request Body schema: application/json

Route to create

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

required
object
object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

object

Responses

Request samples

Content type
application/json
{
  • "host": "a-hostname",
  • "path": "/some_path",
  • "port": 6666,
  • "relationships": {
    },
  • "options": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "protocol": "string",
  • "host": "string",
  • "path": "string",
  • "port": 0,
  • "url": "string",
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

List destinations for a route

Retrieve all destinations associated with a route.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

Responses

Response samples

Content type
application/json
{}

Insert destinations for a route

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

Weighted destinations (deprecated) cannot be added with this endpoint.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

A list of route destinations

Array of objects (RouteDestination)

List of destinations to add to route; destinations without process.type specified will get process type "web" by default

Responses

Request samples

Content type
application/json
{
  • "destinations": [
    ]
}

Response samples

Content type
application/json
{}

Replace all destinations for a route

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

A list of route destinations

Array of objects (RouteDestination)

List of destinations to add to route; destinations without process.type specified will get process type "web" by default

Responses

Request samples

Content type
application/json
{
  • "destinations": [
    ]
}

Response samples

Content type
application/json
{}

Update a destination protocol for a route

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

destination_guid
required
string <uuid>

The GUID of the route destination

Request Body schema: application/json
required

Protocol of the destination

protocol
required
string
Enum: "http1" "http2"

Protocol of the destination

Responses

Request samples

Content type
application/json
{
  • "protocol": "http2"
}

Response samples

Content type
application/json
{}

Remove destination for a route

Remove a destination from a route.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

destination_guid
required
string <uuid>

The GUID of the route destination to remove

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List routes for an app

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

domain_guids
Array of strings

Comma-delimited list of domain guids to filter by

hosts
Array of strings

Comma-delimited list of hostnames to filter by

paths
Array of strings

Comma-delimited list of paths to filter by

ports
Array of integers

Comma-delimited list of ports to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": []
}

Get a route

Retrieve a route.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
include
Array of strings
Items Enum: "domain" "space" "space.organization"

Optionally include a list of unique related resources in the response

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "protocol": "string",
  • "host": "string",
  • "path": "string",
  • "port": 0,
  • "url": "string",
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

Update a route

Update a route.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Route object that needs to be updated

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "protocol": "string",
  • "host": "string",
  • "path": "string",
  • "port": 0,
  • "url": "string",
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

Delete a route

Delete a route.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List shared spaces relationship

Lists the spaces that the route has been shared to.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

List of spaces to share the route with

Array of objects (Relationship)
object

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

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

Unshares a route that was shared with another space.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

space_guid
required
string <uuid>

The GUID of the space to unshare the route from

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

The space to transfer ownership to

Relationship (object) or null
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Route Policies

Route policies control which callers can access routes on identity-aware domains.

List route policies

Retrieve all route policies the user has access to.

Filtering examples

  • Filter by route: GET /v3/route_policies?route_guids=89b32bd6-688f-4424-b94f-2e2c86495a5f
  • Filter by space: GET /v3/route_policies?space_guids=3fa85f64-5717-4562-b3fc-2c963f66afa6
  • Filter by source type: GET /v3/route_policies?sources=cf:any
  • Find policies referencing a specific app: GET /v3/route_policies?source_guids=d76446a1-f429-4444-8797-be2f78b75b08
  • Include source resources: GET /v3/route_policies?include=source (batch-loads the app, space, or org referenced in each policy's source)
  • Include route and source: GET /v3/route_policies?include=route,source

This feature is experimental and is subject to change.

Permitted roles: Admin, Admin Read-Only, Global Auditor, Org Manager, Org Auditor, Org Billing Manager (will receive an empty list), Space Auditor, Space Developer, Space Manager, Space Supporter

Authorizations:
oauth
query Parameters
guids
Array of strings

Comma-delimited list of route policy guids to filter by

route_guids
Array of strings

Comma-delimited list of route guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by (filters by the route's space)

sources
Array of strings

Comma-delimited list of exact source strings to filter by (e.g., cf:any, cf:app:guid)

source_guids
Array of strings

Comma-delimited list of GUIDs to filter by; matches the GUID portion of the source (e.g. the app, space, or org GUID)

page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Enum: "created_at" "-created_at" "updated_at" "-updated_at"

Value to sort by. Defaults to ascending; prepend with - to sort descending. Valid values are created_at, updated_at

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

include
Array of strings
Items Enum: "route" "source"

Optionally include related resources in the response; valid values are route and source (source includes the app, space, or organization based on the source type)

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{}

Create a route policy

Create a route policy granting the given source access to a route on an identity-aware domain.

Validation rules

  • The route's domain must have enforce_route_policies set to true
  • The route's domain must not be internal (internal routes bypass GoRouter)
  • The source must be unique per route (duplicate sources are rejected)
  • If the route already has a cf:any policy, no other sources can be added
  • If adding cf:any, the route must not have any existing policies
  • The source GUID is not checked for existence at creation time; stale references are tolerated, and sources referencing resources the caller cannot see are accepted but do not appear under ?include=source
  • The app, space, and organization relationships are derived from source and cannot be set directly

Common use cases

  • Allow a frontend app to call a backend API: create a policy with source of cf:app:<frontend-app-guid> on the backend route
  • Allow all apps in a space to access a shared service: create a policy with source of cf:space:<space-guid> on the shared service route
  • Open a route to any caller (public API): create a policy with source of cf:any

This feature is experimental and is subject to change.

Permitted roles: Admin, Space Developer (can create policies for routes in spaces they can write to)

Authorizations:
oauth
Request Body schema: application/json
required

Route policy to create

source
required
string

The policy selector. Must be cf:app:<uuid>, cf:space:<uuid>, cf:org:<uuid>, or cf:any

required
object

A relationship to the route this policy applies to

object (Metadata)

Labels and annotations applied to the route policy

Responses

Request samples

Content type
application/json
Example
{
  • "source": "cf:app:d76446a1-f429-4444-8797-be2f78b75b08",
  • "relationships": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

Get a route policy

Retrieve a single route policy.

This feature is experimental and is subject to change.

Permitted roles: Admin, Admin Read-Only, Global Auditor, Org Manager, Org Auditor, Org Billing Manager (will not be able to see any route policies), Space Auditor, Space Developer, Space Manager, Space Supporter

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
include
Array of strings
Items Enum: "route" "source"

Optionally include a list of unique related resources in the response; valid values are route and source (source includes the app, space, or organization referenced by the source field)

Responses

Response samples

Content type
application/json
{}

Update a route policy

Update the metadata of a route policy.

Note: This endpoint only supports updating metadata (labels and annotations). The source and route relationship are immutable after creation. To change the source, delete the policy and create a new one.

This feature is experimental and is subject to change.

Permitted roles: Admin, Space Developer (can update policies for routes in spaces they can write to)

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Route policy metadata to update

object (Metadata)

Labels and annotations applied to the route policy

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

Delete a route policy

Deleting a route policy removes the access control for that specific source. If this was the only policy on the route, the route will become inaccessible (no callers will be allowed) until new policies are added or a cf:any policy is created.

This feature is experimental and is subject to change.

Permitted roles: Admin, Space Developer (can delete policies for routes in spaces they can write to)

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Security Groups

Security groups are used to control access to apps.

List security groups

List security groups.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

guids
Array of strings

Comma-separated list of resource GUIDs to filter by

names
Array of strings

Comma-separated list of names to filter by (case insensitive)

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
Array of strings

Comma-delimited list of space guids to filter by

staging_space_guids
Array of strings

Comma-delimited list of space guids to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a security group

Create a security group.

Authorizations:
oauth
Request Body schema: application/json

Request body for create a security group.

name
required
string

Name of the security group

object
Array of objects

Rules for the security group

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "my-group0",
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2020-02-20T17:42:08Z",
  • "updated_at": "2020-02-20T17:42:08Z",
  • "name": "my-group0",
  • "globally_enabled": {
    },
  • "rules": [
    ],
  • "relationships": {
    },
  • "links": {}
}

Get a security group

Get a security group.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2020-02-20T17:42:08Z",
  • "updated_at": "2020-02-20T17:42:08Z",
  • "name": "my-group0",
  • "globally_enabled": {
    },
  • "rules": [
    ],
  • "relationships": {
    },
  • "links": {}
}

Update a security group

Update a security group.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for update a security group.

name
string

Name of the security group

object
Array of objects

Rules for the security group

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "globally_enabled": {
    },
  • "rules": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2020-02-20T17:42:08Z",
  • "updated_at": "2020-02-20T17:42:08Z",
  • "name": "my-group0",
  • "globally_enabled": {
    },
  • "rules": [
    ],
  • "relationships": {
    },
  • "links": {}
}

Delete a security group

Delete a security group.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Bind a running security group to 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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for bind a running security group to spaces.

Array of objects (Relationship)
object

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Unbind a running security group from a space

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

space_guid
required
string <uuid>

The unique identifier for the space

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Bind a staging security group to 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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for bind a staging security group to spaces.

Array of objects (Relationship)
object

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Unbind a staging security group from a space

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

space_guid
required
string <uuid>

The unique identifier for the space

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Service Brokers

Service brokers are used to manage services.

List service brokers

This endpoint retrieves the service brokers the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

names
Array of strings

Comma-delimited list of service broker names to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{}

Create a service broker

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.

Authorizations:
oauth
Request Body schema: application/json

Service broker to create

name
required
string

Name of the service broker

url
required
string <uri>

URL of the service broker

object

Authentication details for the service broker

object

Relationships for the service broker

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "my_service_broker",
  • "url": "https://example.service-broker.com",
  • "authentication": {
    },
  • "relationships": {
    }
}

Response samples

Content type
{
  • "errors": [
    ]
}

Get a service broker

This endpoint retrieves the service broker by GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Update a service broker

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Service broker object that needs to be updated

name
string

Name of the service broker

url
string

URL of the service broker

object

Credentials used to authenticate against the service broker

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "my_service_broker",
  • "url": "https://example.service-broker.com",
  • "authentication": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

Delete a service broker

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Service Credential Bindings

Service credential bindings are used to bind a service instance to an app.

List service credential bindings

This endpoint retrieves the service credential bindings the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

names
Array of strings

Comma-delimited list of service credential binding names to filter by

service_instance_guids
Array of strings

Comma-delimited list of service instance guids to filter by

app_guids
Array of strings

Comma-delimited list of app guids to filter by

type
string
Enum: "app" "key"

Type of credential binding to filter by. Valid values are 'app' or 'key'

service_instance_names
Array of strings

Comma-delimited list of service instance names to filter by

app_names
Array of strings

Comma-delimited list of app names to filter by

service_plan_guids
Array of strings

Comma-delimited list of service plan guids to filter by

service_plan_names
Array of strings

Comma-delimited list of service plan names to filter by

service_offering_guids
Array of strings

Comma-delimited list of service offering guids to filter by

service_offering_names
Array of strings

Comma-delimited list of service offering names to filter by

guids
Array of strings

Comma-delimited list of service credential binding guids to filter by

include
Array of strings
Items Enum: "app" "service_instance"

Optionally include a list of unique related resources in the response. Valid values are: app, service_instance

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ],
  • "included": {
    }
}

Create a service credential binding

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

Authorizations:
oauth
Request Body schema: application/json

A request to create a service credential binding

type
required
string
Enum: "app" "key"

Type of the service credential binding. Valid values are key and app

name
string

Name of the service credential binding. name is optional when the type is app

required
object

Relationships for the service credential binding

parameters
object

A JSON object that is passed to the service broker

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "app",
  • "name": "some-binding-name",
  • "relationships": {
    },
  • "parameters": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

Get a service credential binding

This endpoint retrieves the service credential binding by GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
include
Array of strings
Items Enum: "app" "service_instance"

Optionally include a list of unique related resources in the response

Responses

Response samples

Content type
application/json
Example
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "app",
  • "name": "string",
  • "last_operation": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    },
  • "included": {
    }
}

Update a service credential binding

This endpoint updates a service credential binding with labels and annotations.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

A request to update a service credential binding

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
Example
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

Delete a service credential binding

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get a service credential binding details

This endpoint retrieves the service credential binding details.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{ }

Get parameters for a service credential binding

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "foo": "bar",
  • "foz": "baz"
}

Service Instances

Service instances are instances of a service.

List service instances

This endpoint retrieves the service instances the user has access to, including access granted by service instance sharing.

Authorizations:
oauth
query Parameters
names
Array of strings

Comma-delimited list of service instance names to filter by

guids
Array of strings

Comma-delimited list of service instance guids to filter by

type
string
Enum: "managed" "user-provided"

Filter by type; valid values are 'managed' and 'user-provided'

space_guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

service_plan_guids
Array of strings

Comma-delimited list of service plan guids to filter by

service_plan_names
Array of strings

Comma-delimited list of service plan names to filter by

page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

fields
object

Fields to include in the response

Responses

Response samples

Content type
application/json
{}

Create a service instance

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

Authorizations:
oauth
Request Body schema: application/json

A request to create a service instance

type
required
string
Enum: "managed" "user-provided"

The type of service instance

name
required
string

Name of the service instance

parameters
object

A JSON object that is passed to the service broker

credentials
object

A JSON object that is made available to apps bound to this service instance (user-provided services only)

tags
Array 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 (user-provided services only)

route_service_url
string

URL to which requests for bound routes will be forwarded; must use the https protocol (user-provided services only)

required
object

Relationships for the service instance

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "managed",
  • "name": "my_service_instance",
  • "parameters": {
    },
  • "tags": [
    ],
  • "metadata": {
    },
  • "relationships": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "user-provided",
  • "name": "string",
  • "tags": [
    ],
  • "syslog_drain_url": "http://example.com",
  • "route_service_url": "http://example.com",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Get a service instance

This endpoint retrieves the service instance by GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
fields
object

Fields to include in the response

Responses

Response samples

Content type
application/json
Example
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "managed",
  • "name": "string",
  • "tags": [
    ],
  • "syslog_drain_url": "http://example.com",
  • "route_service_url": "http://example.com",
  • "dashboard_url": "http://example.com",
  • "maintenance_info": {
    },
  • "upgrade_available": true,
  • "last_operation": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Update a 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 has allow_context_updates feature enabled

Otherwise the response will be synchronous.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

A request to update a service instance

name
string

Name of the service instance

parameters
object

A JSON object that is passed to the service broker (managed services only)

credentials
object

A JSON object that is made available to apps bound to this service instance (user-provided services only)

tags
Array 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 (user-provided services only)

route_service_url
string

URL to which requests for bound routes will be forwarded; must use the https protocol (user-provided services only)

object

Relationships for the service instance

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

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_service_instance",
  • "parameters": {
    },
  • "tags": [
    ],
  • "relationships": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
Example
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "managed",
  • "name": "string",
  • "tags": [
    ],
  • "syslog_drain_url": "http://example.com",
  • "route_service_url": "http://example.com",
  • "dashboard_url": "http://example.com",
  • "maintenance_info": {
    },
  • "upgrade_available": true,
  • "last_operation": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Delete a service instance

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
purge
boolean

If true, deletes the service instance and all associated resources without any interaction with the service broker.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get credentials for a user-provided service instance

Retrieves the credentials for a user-provided service instance. This endpoint is not available for managed service instances.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "username": "my-username",
  • "password": "super-secret",
  • "other": "credential"
}

Get parameters for a managed service instance

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "key_1": "value_1",
  • "key_2": "value_2"
}

Get permissions for a service instance

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "read": true,
  • "manage": false
}

List shared spaces relationship

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
fields
object

Fields to include in the response

Responses

Response samples

Content type
application/json
{}

Share a service instance to other 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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for share a service instance to other spaces.

Array of objects (Relationship)
object

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{}

Get usage summary in shared spaces

This endpoint returns the number of bound apps in spaces where the service instance has been shared to.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Unshare a service instance from another space

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

space_guid
required
string <uuid>

GUID of the space.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Service Offerings

Service offerings are services that are available to be used.

List service offerings

This endpoint retrieves the service offerings the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

names
Array of strings

Comma-delimited list of service offering names to filter by

available
boolean

Filter by the available property; valid values are true or false

service_broker_guids
Array of strings

Comma-delimited list of service broker GUIDs to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

service_broker_names
Array of strings

Comma-delimited list of service broker names to filter by

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

fields
object

Fields to include in the response

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{}

Get a service offering

This endpoint retrieves the service offering by GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Update a service offering

This endpoint updates a service offering with labels and annotations.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for update a service offering.

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

Delete a service offering

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
purge
boolean

If true, any service plans, instances, and bindings associated with this service offering will also be deleted

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Service Plans

Service plans are plans for a service.

List service plans

This endpoint retrieves the service plans the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

names
Array of strings

Comma-delimited list of service plan names to filter by

available
boolean

Filter by the available property; valid values are true or false

service_offering_guids
Array of strings

Comma-delimited list of service offering guids to filter by

service_instance_guids
Array of strings

Comma-delimited list of service instance guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

broker_catalog_ids
Array of strings

Comma-delimited list of broker catalog IDs to filter by

service_broker_guids
Array of strings

Comma-delimited list of service broker GUIDs to filter by

service_broker_names
Array of strings

Comma-delimited list of service broker names to filter by

service_offering_names
Array of strings

Comma-delimited list of service offering names to filter by

include
Array of strings
Items Enum: "space.organization" "service_offering"

Optionally include a list of unique related resources in the response

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

fields
object

Fields to include in the response

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ],
  • "included": {
    }
}

Get a service plan

This endpoint retrieves the service plan by GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
include
Array of strings
Items Enum: "space.organization" "service_offering"

Optionally include a list of unique related resources in the response

Responses

Response samples

Content type
application/json
{}

Update a service plan

This endpoint updates a service plan with labels and annotations.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for update a service plan.

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "service_offering_guid": "string",
  • "service_offering_name": "string",
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

Delete a service plan

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get a service plan visibility

This endpoint retrieves the service plan visibility for a given plan.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "type": "public"
}

Update a service plan visibility

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Service plan visibility object that needs to be updated

type
required
string
Enum: "public" "admin" "organization"

Denotes the visibility of the plan

Array of objects

Desired list of organizations GUIDs where the plan will be accessible; required if type is organization

Responses

Request samples

Content type
application/json
{
  • "type": "public",
  • "organizations": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "public",
  • "organizations": [
    ]
}

Apply a service plan visibility

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Service plan visibility object that needs to be created

type
required
string
Enum: "public" "admin" "organization"

Denotes the visibility of the plan

Array of objects

Desired list of organizations GUIDs where the plan will be accessible; required if type is organization

Responses

Request samples

Content type
application/json
{
  • "type": "organization",
  • "organizations": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "organization"
}

Remove organization from a service plan visibility

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

organization_guid
required
string <uuid>

GUID of the organization.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Service Route Bindings

Service route bindings are used to bind a route to a service instance.

List service route bindings

This endpoint retrieves the service route bindings the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

route_guids
Array of strings

Comma-delimited list of route guids to filter by

service_instance_guids
Array of strings

Comma-delimited list of service instance guids to filter by

service_instance_names
Array of strings

Comma-delimited list of service instance names to filter by

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of service route binding guids to filter by

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

include
Array of strings
Items Enum: "route" "service_instance"

Optionally include a list of unique related resources in the response. Valid values are: route, service_instance

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ],
  • "included": {
    }
}

Create a service route binding

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.

Authorizations:
oauth
Request Body schema: application/json

Request body for create a service route binding.

required
object

Relationships for the service route binding

parameters
object

A JSON object that is passed to the service broker

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "relationships": {
    },
  • "parameters": {
    }
}

Response samples

Content type
application/json
{}

Get a service route binding

This endpoint retrieves the service route binding by GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
include
Array of strings
Items Enum: "route" "service_instance"

Optionally include a list of unique related resources in the response

Responses

Response samples

Content type
application/json
{}

Update a service route binding

This endpoint updates a service route binding with labels and annotations.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for update a service route binding.

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{}

Delete a service route binding

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get parameters for a route binding

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "foo": "bar",
  • "foz": "baz"
}

Service Usage Events

Service usage events are a record of changes in the usage of services.

List service usage events

Retrieve all service usage events the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

after_guid
string

Filters out events before and including the event with the given guid.

guids
Array of strings

Comma-delimited list of usage event guids to filter by.

service_instance_types
Array of strings
Items Enum: "managed_service_instance" "user_provided_service_instance"

Comma-delimited list of service instance types to filter by; valid values are managed_service_instance and user_provided_service_instance

service_offering_guids
Array of strings

Comma-delimited list of service offering guids to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get a service usage event

Retrieve a service usage event.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2020-05-28T12:34:56Z",
  • "updated_at": "2020-05-28T12:34:56Z",
  • "state": "CREATED",
  • "space": {
    },
  • "organization": {
    },
  • "service_instance": {
    },
  • "service_plan": {
    },
  • "service_offering": {
    },
  • "service_broker": {
    },
  • "links": {}
}

Purge and seed service usage events

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.

Authorizations:
oauth

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

Sidecars

Sidecars are used to run a process alongside an app.

Get a sidecar

Get a sidecar.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "auth-sidecar",
  • "command": "bundle exec rackup",
  • "process_types": [
    ],
  • "memory_in_mb": 300,
  • "origin": "user",
  • "relationships": {
    },
  • "created_at": "2017-02-01T01:33:58Z",
  • "updated_at": "2017-02-01T01:33:58Z"
}

Update a sidecar

Update a sidecar.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Sidecar object that needs to be updated

name
string

Human-readable name for the sidecar

command
string

The command used to start the sidecar

process_types
Array of strings

A list of process types the sidecar applies to

memory_in_mb
integer

Reserved memory for sidecar

Responses

Request samples

Content type
application/json
{
  • "name": "auth-sidecar",
  • "command": "bundle exec rackup",
  • "process_types": [
    ],
  • "memory_in_mb": 300
}

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "auth-sidecar",
  • "command": "bundle exec rackup",
  • "process_types": [
    ],
  • "memory_in_mb": 300,
  • "origin": "user",
  • "relationships": {
    },
  • "created_at": "2017-02-01T01:33:58Z",
  • "updated_at": "2017-02-01T01:33:58Z"
}

Delete a sidecar

Delete a sidecar.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List sidecars for app

Retrieves all sidecars associated with a app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "resources": [
    ]
}

Create a sidecar associated with an app

Create a sidecar associated with an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Sidecar to create

name
string

Name of the sidecar

command
string

Command to run for the sidecar

process_types
Array of strings

Process types that the sidecar applies to

memory_in_mb
integer

Memory limit for the sidecar in MB

Responses

Request samples

Content type
application/json
{
  • "name": "auth-sidecar",
  • "command": "bundle exec rackup",
  • "process_types": [
    ],
  • "memory_in_mb": 300
}

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "auth-sidecar",
  • "command": "bundle exec rackup",
  • "process_types": [
    ],
  • "memory_in_mb": 300,
  • "origin": "user",
  • "relationships": {
    },
  • "created_at": "2017-02-01T01:33:58Z",
  • "updated_at": "2017-02-01T01:33:58Z"
}

List sidecars for process

Retrieves all sidecars associated with a process.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "resources": [
    ]
}

Spaces

Spaces are used to group apps and services.

List spaces

Retrieve all spaces the user has access to.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

names
Array of strings

Comma-delimited list of space names to filter by

guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

include
Array of strings
Items Value: "organization"

Optionally include a list of unique related resources in the response

Responses

Response samples

Content type
application/json
{}

Create a space

Create a space.

Authorizations:
oauth
Request Body schema: application/json
required

Space object that needs to be created

name
required
string

Name of the space

required
object
object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "my-space",
  • "relationships": {
    }
}

Response samples

Content type
application/json
{}

Get a space

This endpoint retrieves the specified space object.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
include
Array of strings
Items Value: "organization"

Optionally include additional related resources in the response

Responses

Response samples

Content type
application/json
{}

Update a space

Update a space

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Space object that needs to be updated

name
string

New space name

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "new-space-name"
}

Response samples

Content type
application/json
{}

Delete a space

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
{
  • "errors": [
    ]
}

Apply a manifest to a space

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, app features, routes, or services.

Apply manifest will only trigger an immediate update for the “instances” property or routing changes. All other properties require an app restart to take effect.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/x-yaml

Request body for apply a manifest to a space.

string

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List space features

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "resources": [
    ]
}

Get a space feature

Get a space feature

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

name
required
string
Value: "ssh"

Name of the feature.

Responses

Response samples

Content type
application/json
{
  • "name": "ssh",
  • "description": "Enable SSHing into apps in the space.",
  • "enabled": true
}

Update a space feature

Update a space feature.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

name
required
string
Value: "ssh"

Name of the feature.

Request Body schema: application/json

Request body for update a space feature.

enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "name": "ssh",
  • "description": "Enable SSHing into apps in the space.",
  • "enabled": true
}

Create a manifest diff for a space (experimental)

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/x-yaml

Request body for create a manifest diff for a space (experimental).

string

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get assigned isolation segment

Get assigned isolation segment

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

Manage isolation segment

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

Apps will not run in the newly assigned isolation segment until they are restarted.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for manage isolation segment.

Relationship (object) or null
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{}

Delete unmapped routes for a space

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
unmapped
required
boolean
Value: true

Filter to only delete unmapped routes

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get usage summary for a space

This endpoint retrieves the specified space's memory and app instance usage summary.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{}

List running security groups for a space

This endpoint returns security groups that are enabled for running globally or at the space level for the given space.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

List staging security groups for a space

This endpoint returns security groups that are enabled for staging globally or at the space level for the given space.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

List users for a space

Retrieve all users with a role in the specified space.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Space Quotas

Space quotas are named sets of memory, log rate, service, and instance usage quotas.

List space quotas

This endpoint lists all space quota resources that the user has permission to view.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

guids
Array of strings

Comma-delimited list of space quota guids to filter by

names
Array of strings

Comma-delimited list of space quota names to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

Responses

Response samples

Content type
application/json
{}

Create a space quota

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

Authorizations:
oauth
Request Body schema: application/json

Space quota to create

name
required
string

Name of the space quota

object

App limits for the space quota

object

Service limits for the space quota

object

Route limits for the space quota

object

Relationships for the space quota

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "production",
  • "relationships": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2016-05-04T17:00:41Z",
  • "updated_at": "2016-05-04T17:00:41Z",
  • "name": "don-quixote",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "relationships": {
    },
  • "links": {}
}

Get a space quota

Get a space quota

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2016-05-04T17:00:41Z",
  • "updated_at": "2016-05-04T17:00:41Z",
  • "name": "don-quixote",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "relationships": {
    },
  • "links": {}
}

Update a space quota

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Space quota to update

name
string

Name of the space quota

object

App limits for the space quota

object

Service limits for the space quota

object

Route limits for the space quota

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000",
  • "created_at": "2016-05-04T17:00:41Z",
  • "updated_at": "2016-05-04T17:00:41Z",
  • "name": "don-quixote",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "relationships": {
    },
  • "links": {}
}

Delete a space quota

Space quotas cannot be deleted when applied to any spaces.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Apply a space quota to a space

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.

Authorizations:
oauth
path Parameters
quota_guid
required
string <uuid>

GUID of the quota.

Request Body schema: application/json

Request body for apply a space quota to a space.

Array of objects (Relationship)
object

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{}

Remove a space quota from a space

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

space_guid
required
string <uuid>

GUID of the space.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Stacks

Stacks are used to specify the operating system and runtime environment for an app.

List stacks

Retrieve all stacks.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

names
Array of strings

Comma-delimited list of stack names to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "resources": [
    ]
}

Create a stack

Create a stack.

Authorizations:
oauth
Request Body schema: application/json
required

Stack object that needs to be created

name
required
string <= 250 characters

Name of the stack; must be unique and no longer than 250 characters

description
string or null <= 250 characters

Description of the stack; must no longer than 250 characters

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "build_rootfs_image": "string",
  • "run_rootfs_image": "string",
  • "default": true,
  • "links": {
    },
  • "metadata": {
    }
}

Get a stack

Get a stack.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "build_rootfs_image": "string",
  • "run_rootfs_image": "string",
  • "default": true,
  • "links": {
    },
  • "metadata": {
    }
}

Update a stack

Update a stack.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for update a stack.

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

state
string
Enum: "ACTIVE" "DEPRECATED" "RESTRICTED" "DISABLED"
state_reason
string or null

Optional explanation of the stack state change.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "state": "ACTIVE",
  • "state_reason": "Optional plain text describing the stack state change"
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "build_rootfs_image": "string",
  • "run_rootfs_image": "string",
  • "default": true,
  • "links": {
    },
  • "metadata": {
    }
}

Delete a stack

Delete a stack.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List apps on a stack

Retrieve all apps using a given stack.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

Responses

Response samples

Content type
application/json
{}

Tasks

Tasks are one-off commands that can be run against an app.

List tasks

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

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of task guids to filter by

names
Array of strings

Comma-delimited list of task names to filter by

states
Array of strings
Items Enum: "PENDING" "RUNNING" "SUCCEEDED" "CANCELING" "FAILED"

Comma-delimited list of task states to filter by

app_guids
Array of strings

Comma-delimited list of app guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

sequence_ids
Array of integers

Comma-delimited list of sequence ids to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get a task

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

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "command": "string",
  • "state": "PENDING",
  • "sequence_id": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "droplet_guid": "string",
  • "result": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Update a task

Update a task.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Request body for update a task.

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "command": "string",
  • "state": "PENDING",
  • "sequence_id": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "droplet_guid": "string",
  • "result": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Cancel a task

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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "command": "string",
  • "state": "PENDING",
  • "sequence_id": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "droplet_guid": "string",
  • "result": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Cancel a task (PUT)

Cancels a running task using PUT method. 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.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "command": "string",
  • "state": "PENDING",
  • "sequence_id": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "droplet_guid": "string",
  • "result": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

DEPRECATED - Cancel a task (short path)

DEPRECATED - Use /v3/tasks/{guid}/actions/cancel instead.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "command": "string",
  • "state": "PENDING",
  • "sequence_id": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "droplet_guid": "string",
  • "result": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

List tasks for an app

Retrieve tasks for an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of task guids to filter by

names
Array of strings

Comma-delimited list of task names to filter by

states
Array of strings
Items Enum: "PENDING" "RUNNING" "SUCCEEDED" "CANCELING" "FAILED"

Comma-delimited list of task states to filter by

sequence_ids
Array of integers

Comma-delimited list of sequence ids to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a task

Create a task.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Task object that needs to be created

command
string

The command to run for the task. NOTE: optional if a template.process.guid is provided

name
string

Human-readable name for the task

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

Amount of log rate limit to allocate for the task in bytes per second

droplet_guid
string <uuid>

The GUID of a droplet to use to run the task

object

An object with a process field to template the task from

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "command": "string",
  • "state": "PENDING",
  • "sequence_id": 0,
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "droplet_guid": "string",
  • "result": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Users

Users are the users of the Cloud Foundry platform.

List users

Retrieve all users that the current user can see.

Authorizations:
oauth
query Parameters
page
integer
Example: page=1

Page to display; valid values are integers >= 1

per_page
integer
Example: per_page=50

Number of results per page, valid values are 1 through 5000

order_by
string
Example: order_by=created_at

Value to sort by. Defaults to ascending; prepend with - to sort descending.

created_ats
string
Example: created_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

updated_ats
string
Example: updated_ats=2021-01-01T00:00:00Z

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with relational operators.

label_selector
string
Example: label_selector=environment=production

A query string containing a list of label selector requirements

guids
Array of strings

Comma-delimited list of user guids to filter by (can include UAA user IDs or client IDs)

usernames
Array of strings

Comma-delimited list of usernames to filter by

origins
Array of strings

Comma-delimited list of user origins to filter by

partial_usernames
Array of strings

Comma-delimited list of partial usernames to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "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. Creating a user by guid is only permitted by admins.

If CAPI property cc.allow_user_creation_by_org_manager is enabled, a UAA user will be automatically created if it does not exist yet. The UAA user will be only created when username and origin have been provided instead of a guid. Additionally origin must be different from uaa. Admins and OrgManagers can make use of the UAA user creation.

Authorizations:
oauth
Request Body schema: application/json

User to create

guid
string

Unique identifier for the user

username
string

Username of the user to be created. This can only be provided together with origin

origin
string

Origin of the user to be created. This can only be provided together with username and cannot be uaa

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
Example
{
  • "guid": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "guid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Get a user

Retrieve a user.

Authorizations:
oauth
path Parameters
guid
required
string

The unique identifier for the user, matching either a UAA user id or client id. A client id may not be a uuid.

Responses

Response samples

Content type
application/json
{
  • "guid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Update a user

Update a user's metadata.

Authorizations:
oauth
path Parameters
guid
required
string

The unique identifier for the user, matching either a UAA user id or client id. A client id may not be a uuid.

Request Body schema: application/json

User to update

username
string

The username of the user

presentation_name
string

The presentation name of the user

origin
string

The origin of the user

object (Metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

object
object

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "rate_limits": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Delete a user

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

Authorizations:
oauth
path Parameters
guid
required
string

The unique identifier for the user, matching either a UAA user id or client id. A client id may not be a uuid.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}