API docs by Redocly

Cloud Foundry V3 API (alpha-0.0.1)

Download OpenAPI specification:

Cloud Foundry CAPI Team: cf-dev@lists.cloudfoundry.org URL: https://cloudfoundry.slack.com/archives/C07C04W4Q License: Apache 2.0

Welcome to the Cloud Foundry V3 API documentation. Version 3 introduces several key features, including the ability to run one-off tasks on Cloud Foundry, support for applications with multiple processes defined via a Procfile, direct access to application packages and droplets, and the ability to update application source code without stopping the app through deployments.

For help or questions regarding the API, the CAPI team is best reached through our Slack channel. If you encounter issues with the API or its documentation, please consider submitting a GitHub issue in the cloud_controller_ng repository. We recommend using Slack first, as we are most responsive there.

Additional resources include the deprecated but still available Cloud Foundry V2 API, documentation on running tasks, and the source code for the V3 API documentation and OpenAPI specification.

AppFeatures

AppFeatures provide additional capabilities and configurations for apps. These features can include things like auto-scaling, health checks, and custom domains. AppFeatures enhance the functionality of apps by allowing developers to enable or disable specific features based on their requirements. They can be managed through endpoints that allow for enabling, disabling, and retrieving the status of app features.

Apps

Apps represent the core entities in the Cloud Foundry environment. They are the deployable units that run your code. Each app can have multiple processes, routes, and services associated with it. Apps can be scaled horizontally by increasing the number of instances. They can also be updated and restarted as needed. The lifecycle of an app includes stages such as staging, starting, running, and stopping. Apps can be managed through various endpoints that allow for creation, updating, deletion, and retrieval of app details.

List apps

Retrieve all apps the user has access to.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ],
  • "included": {
    }
}

Create an app

Creates a new app.

Authorizations:
beareroauth
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": "string",
  • "environment_variables": {
    },
  • "lifecycle": {
    },
  • "relationships": {
    },
  • "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",
  • "state": "STOPPED",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

Get an app

Retrieve a specific app.

Authorizations:
beareroauth
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
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "state": "STOPPED",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

Update an app

Update an app.

Authorizations:
beareroauth
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": "string",
  • "environment_variables": {
    },
  • "lifecycle": {
    },
  • "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",
  • "state": "STOPPED",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

Delete an app

Delete an app.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Start an app

Start an app.

Authorizations:
beareroauth
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": "STOPPED",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

Stop an app

Stop an app.

Authorizations:
beareroauth
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": "STOPPED",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

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:
beareroauth
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": "STOPPED",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    },
  • "included": {
    }
}

Get current droplet

Get the current droplet for an app.

Authorizations:
beareroauth
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": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "links": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

Get current droplet association for an app

This endpoint retrieves the current droplet relationship for an app.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

Set current droplet

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

Authorizations:
beareroauth
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
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc"
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Update environment variables for the 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
{
  • "var": {
    },
  • "links": {
    }
}

List app features

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

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Get an app feature

Get an app feature.

Authorizations:
beareroauth
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 identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Update an app feature

Update an app feature.

Authorizations:
beareroauth
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 identifier

Request Body schema: application/json

Update the named app feature, enabling or disabling it.

enabled
boolean

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
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": true
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

AppUsageEvents

AppUsageEvents track the usage and activity of apps within the Cloud Foundry environment. These events provide insights into app lifecycle changes, such as creation, deletion, scaling, and crashes. AppUsageEvents are useful for monitoring and auditing purposes, helping administrators understand how apps are being used and identify any issues. They can be retrieved through endpoints that provide detailed information about each event.

List app usage events

Retrieve all app usage events.

Authorizations:
beareroauth
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:
beareroauth
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": {
    },
  • "app": {
    },
  • "process": {
    },
  • "space": {
    },
  • "organization": {
    },
  • "buildpack": {
    },
  • "task": {
    },
  • "memory_in_mb_per_instance": {
    },
  • "instance_count": {
    }
}

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:
beareroauth

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

AuditEvents

AuditEvents capture significant actions and changes within the Cloud Foundry environment. These events include actions performed by users, such as creating, updating, or deleting resources. AuditEvents provide a comprehensive audit trail that helps administrators track changes and ensure compliance with organizational policies. They can be retrieved through endpoints that provide detailed information about each event, including the user who performed the action and the affected resources.

List audit events

Retrieve all audit events the user has access to.

Authorizations:
beareroauth
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:
beareroauth
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": "string",
  • "actor": {
    },
  • "target": {
    },
  • "data": { },
  • "space": {
    },
  • "organization": {
    },
  • "links": {
    }
}

Buildpacks

Buildpacks are responsible for detecting, compiling, and packaging apps in the Cloud Foundry environment. They provide the necessary runtime and dependencies for the app to run. Buildpacks can be customized and extended to support different languages and frameworks. They can be managed through endpoints that allow for creation, updating, deletion, and retrieval of buildpack details.

List buildpacks

Retrieve all buildpacks.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a buildpack

Create a buildpack.

Authorizations:
beareroauth
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": "string",
  • "stack": "string",
  • "position": 0,
  • "lifecycle": "string",
  • "enabled": true,
  • "locked": true,
  • "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",
  • "state": "AWAITING_UPLOAD",
  • "stack": "string",
  • "lifecycle": "string",
  • "position": 0,
  • "enabled": true,
  • "locked": true,
  • "filename": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Get a buildpack

Retrieve a buildpack.

Authorizations:
beareroauth
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:
beareroauth
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": "string",
  • "position": 0,
  • "enabled": true,
  • "locked": true,
  • "stack": "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",
  • "state": "AWAITING_UPLOAD",
  • "stack": "string",
  • "lifecycle": "string",
  • "position": 0,
  • "enabled": true,
  • "locked": true,
  • "filename": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Delete a buildpack

Delete a buildpack.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
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": {
    }
}

Builds

Builds represent the process of transforming source code into a runnable artifact. In Cloud Foundry, builds are created using buildpacks, which provide the necessary dependencies and configurations for the app. Builds can be triggered manually or automatically as part of the app deployment process. They can be managed through endpoints that allow for creation, updating, deletion, and retrieval of build details.

List builds

Retrieve all builds.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a build

Create a build.

Authorizations:
beareroauth
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": {
    },
  • "lifecycle": {
    },
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "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": {
    }
}

Get a build

Retrieve a build.

Authorizations:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Update build properties such as metadata.

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
{
  • "state": "STAGING",
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "error": "string",
  • "lifecycle": {
    },
  • "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:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Update a build

Update a build.

Authorizations:
beareroauth
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": {
    }
}

Deployments

Deployments represent the process of deploying apps to the Cloud Foundry environment. They include stages such as staging, starting, and running the app. Deployments can be triggered manually or automatically as part of the app lifecycle. They can be managed through endpoints that allow for creation, updating, deletion, and retrieval of deployment details.

List deployments

Retrieve all deployments.

Authorizations:
beareroauth
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:
beareroauth
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 (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
{
  • "relationships": { },
  • "strategy": "rolling",
  • "droplet": {
    },
  • "revision": {
    },
  • "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": {
    }
}

Get a deployment

Retrieve a deployment.

Authorizations:
beareroauth
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:
beareroauth
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:
beareroauth
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:
beareroauth
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 the DNS domains used to route traffic to apps in the Cloud Foundry environment. They can be shared or private, and can be associated with specific organizations or spaces. Domains can be managed through endpoints that allow for creation, updating, deletion, and retrieval of domain details.

List domains

Retrieve all domains the user has access to.

Authorizations:
beareroauth
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 GUIDs to filter by

names
Array of strings

Comma-delimited list of domain names to filter by

organization_guids
Array of strings

Comma-delimited list of owning organization GUIDs to filter by

Responses

Response samples

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

Create a domain

Create a domain.

Authorizations:
beareroauth
Request Body schema: application/json
required

Domain object that needs to be created

name
required
string

Name of the domain

internal
boolean

Whether the domain is used for internal (container-to-container) traffic

object

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

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": "string",
  • "internal": true,
  • "router_group": {
    },
  • "relationships": {
    },
  • "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",
  • "internal": true,
  • "router_group": {
    },
  • "supported_protocols": [
    ],
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Get a domain

Retrieve a domain.

Authorizations:
beareroauth
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": [
    ],
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Update a domain

Update a domain.

Authorizations:
beareroauth
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)

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",
  • "internal": true,
  • "router_group": {
    },
  • "supported_protocols": [
    ],
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Delete a domain

Delete a domain.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

List of organizations to share the domain with

Array of objects (Relationship)

Responses

Request samples

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

Response samples

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

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.

Authorizations:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

query Parameters
host
string

Hostname to filter by

path
string

Path to filter by

port
integer

Port to filter by

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.

Authorizations:
beareroauth
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.

names
Array of strings

Comma-delimited list of domain names to filter by

Responses

Response samples

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

Droplets

Droplets are the runnable artifacts created from builds in the Cloud Foundry environment. They contain the compiled code and dependencies needed to run the app. Droplets can be managed through endpoints that allow for creation, updating, deletion, and retrieval of droplet details.

List droplets for an app

Retrieve all droplets belonging to an app.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

List droplets

Retrieve all droplets.

Authorizations:
beareroauth
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

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

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:
beareroauth
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": { },
  • "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"
}

Get a droplet

Retrieve a droplet.

Authorizations:
beareroauth
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": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "links": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

Update a droplet

Update a droplet.

Authorizations:
beareroauth
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
required
string

Image reference where the built complete image was stored

Responses

Request samples

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

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:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
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:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

EnvironmentVariableGroups

EnvironmentVariableGroups represent collections of environment variables that can be applied to apps in the Cloud Foundry environment. They provide a way to manage and share common configurations across multiple apps. EnvironmentVariableGroups can be managed through endpoints that allow for creation, updating, deletion, and retrieval of environment variable group details.

Get an environment variable group

Retrieve an environment variable group.

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

name identifier

Responses

Response samples

Content type
application/json
{
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "var": {
    },
  • "links": {
    }
}

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:
beareroauth
path Parameters
name
required
string
Enum: "running" "staging"

name identifier

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
{
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "var": {
    },
  • "links": {
    }
}

FeatureFlags

FeatureFlags provide a way to enable or disable specific features in the Cloud Foundry environment. They allow administrators to control the availability of features based on organizational requirements. FeatureFlags can be managed through endpoints that allow for enabling, disabling, and retrieving the status of feature flags.

List feature flags

Retrieve all feature_flags.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get a feature flag

Get a feature flag.

Authorizations:
beareroauth
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
{
  • "name": "string",
  • "enabled": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "custom_error_message": "string",
  • "links": {
    }
}

Update a feature flag

Update a feature flag.

Authorizations:
beareroauth
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": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "custom_error_message": "string",
  • "links": {
    }
}

Info

The Info endpoint provides information about the Cloud Foundry environment, including version details, API endpoints, and other metadata. It is useful for understanding the capabilities and configuration of the environment. The Info endpoint can be accessed to retrieve detailed information about the Cloud Foundry deployment.

Get platform info

Get information about the platform.

Responses

Response samples

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

Get platform usage summary

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

Authorizations:
beareroauth

Responses

Response samples

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

IsolationSegments

IsolationSegments provide a way to isolate apps and resources within the Cloud Foundry environment. They allow for the creation of isolated environments with dedicated resources, such as compute, storage, and networking. IsolationSegments can be managed through endpoints that allow for creation, updating, deletion, and retrieval of isolation segment details.

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.

Authorizations:
beareroauth
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 isolation segment guids to filter by.

names
Array of strings

Comma-delimited list of isolation segment names 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": [
    ]
}

Create an isolation segment

Create an isolation segment.

Authorizations:
beareroauth
Request Body schema: application/json

Isolation segment to create

name
required
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)

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",
  • "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",
  • "metadata": {
    },
  • "links": {
    }
}

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.

Authorizations:
beareroauth
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",
  • "metadata": {
    },
  • "links": {
    }
}

Update an isolation segment

Update an isolation segment.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

Isolation segment to update

name
string

The name of the isolation segment

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",
  • "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",
  • "metadata": {
    },
  • "links": {
    }
}

Delete an isolation segment

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

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Entitle organizations for 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.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json
required

List of organizations to entitle

Array of objects (Relationship)

Responses

Request samples

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

Response samples

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

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.

Authorizations:
beareroauth
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
{
  • "data": [
    ]
}

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.

Authorizations:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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.

Authorizations:
beareroauth
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
{
  • "data": [
    ]
}

Jobs

Jobs represent asynchronous operations in the Cloud Foundry environment. They are used for tasks that may take a long time to complete, such as app deployments, service provisioning, and data migrations. Jobs can be managed through endpoints that allow for creation, updating, deletion, and retrieval of job details.

Get a job

Retrieve a specific job.

Authorizations:
beareroauth
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": {
    }
}

Manifests

Manifests provide a way to define the configuration and deployment details of apps in the Cloud Foundry environment. They include information such as app name, buildpack, environment variables, and services. Manifests can be used to automate the deployment and management of apps. They can be managed through endpoints that allow for creation, updating, deletion, and retrieval of manifest details.

Generate a manifest for an app

Generate a manifest for an app and its underlying processes.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

OrganizationQuotas

OrganizationQuotas define the resource limits and constraints for organizations in the Cloud Foundry environment. They include limits on memory, instances, routes, and services. OrganizationQuotas can be managed through endpoints that allow for creation, updating, deletion, and retrieval of organization quota details.

List organization quotas

This endpoint lists all organization quota resources.

Authorizations:
beareroauth
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
{
  • "total_results": 0,
  • "total_pages": 0,
  • "first": {
    },
  • "last": {
    },
  • "next": {
    },
  • "previous": {
    },
  • "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:
beareroauth
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": "string",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "domains": {
    },
  • "relationships": {
    },
  • "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",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "domains": {
    },
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Get an organization quota

This endpoint gets an individual organization quota resource.

Authorizations:
beareroauth
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",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "domains": {
    },
  • "relationships": {
    },
  • "metadata": {
    },
  • "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:
beareroauth
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": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "domains": {
    },
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Delete an organization quota

Organization quotas cannot be deleted when applied to any organizations.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
path Parameters
quota_guid
required
string <uuid>

quota_guid identifier

Request Body schema: application/json

Apply the organization quota to the given organizations.

Array of objects (Relationship)

Responses

Request samples

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

Response samples

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

Organizations

Organizations represent the top-level entities in the Cloud Foundry environment. They provide a way to group and manage resources, such as apps, spaces, and users. Organizations can be managed through endpoints that allow for creation, updating, deletion, and retrieval of organization details.

List organizations

Retrieve all organizations the user has access to.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create an organization

Create an organization.

Authorizations:
beareroauth
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": "string",
  • "suspended": true,
  • "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",
  • "suspended": true,
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Get an organization

This endpoint retrieves the specified organization object.

Authorizations:
beareroauth
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",
  • "suspended": true,
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Update an organization

Update an organization.

Authorizations:
beareroauth
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": "string",
  • "suspended": true,
  • "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",
  • "suspended": true,
  • "relationships": {
    },
  • "metadata": {
    },
  • "links": {
    }
}

Delete an organization

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

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Get default domain

Retrieve the default domain for a given organization.

Authorizations:
beareroauth
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": [
    ],
  • "relationships": { },
  • "metadata": {
    },
  • "links": {
    }
}

Get usage summary

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

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

List users for an organization

Retrieve all users with a role in the specified organization.

Authorizations:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Set or clear the default isolation segment relationship for the organization.

Relationship (object) or null

Responses

Request samples

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

Response samples

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

Packages

Packages represent the source code and dependencies of apps in the Cloud Foundry environment. They are used to create builds and droplets. Packages can be managed through endpoints that allow for creation, updating, deletion, and retrieval of package details.

List packages

Retrieve all packages.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a package

Create a package.

Authorizations:
beareroauth
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
{
  • "type": "bits",
  • "data": {
    },
  • "relationships": {
    },
  • "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": {
    }
}

Get a package

Retrieve a package.

Authorizations:
beareroauth
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:
beareroauth
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": {
    },
  • "username": "string",
  • "password": "string"
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

List packages for an app

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

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema:

Upload package bits as a multipart form to stage the package content.

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Processes

Processes represent the runnable units of apps in the Cloud Foundry environment. They include information such as command, instances, memory, and disk. Processes can be managed through endpoints that allow for creation, updating, deletion, and retrieval of process details.

List processes

Retrieve all processes.

Authorizations:
beareroauth
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:
beareroauth
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": "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

Update a process.

Authorizations:
beareroauth
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": "string",
  • "health_check": {
    },
  • "readiness_health_check": {
    },
  • "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

Get stats for a process.

Authorizations:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Scale a process by updating instance count and or resource limits.

instances
integer or null or string
memory_in_mb
integer or null or string
disk_in_mb
integer or null or string
log_rate_limit_in_bytes_per_second
integer or null or string

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

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

index
required
integer

index identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

List processes for an app

Retrieves all processes belonging to an app.

Authorizations:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

type identifier

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

type identifier

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": "string",
  • "health_check": {
    },
  • "readiness_health_check": {
    },
  • "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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

type identifier

Responses

Response samples

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

Scale a process for an app

Scale a specific process for an app.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

type identifier

Request Body schema: application/json

Scale an app process of the given type by updating instance count and or resource limits.

instances
integer or null or string
memory_in_mb
integer or null or string
disk_in_mb
integer or null
log_rate_limit_in_bytes_per_second
integer or null

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

type
required
string

type identifier

index
required
integer

index identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

ResourceMatches

ResourceMatches provide a way to identify and reuse existing resources in the Cloud Foundry environment. They help optimize resource usage by matching new resources with existing ones. ResourceMatches can be managed through endpoints that allow for creation, updating, deletion, and retrieval of resource match details.

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:
beareroauth
Request Body schema: application/json

Provide resource descriptors to check which resources already exist on the Cloud Foundry blobstore.

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 the versions of apps in the Cloud Foundry environment. They provide a way to track and manage changes to apps over time. Revisions can be managed through endpoints that allow for creation, updating, deletion, and retrieval of revision details.

Get a revision

Retrieve a revision.

Authorizations:
beareroauth
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:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

List revisions for an app

Retrieve revisions for an app the user has access to.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

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:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Roles

Roles define the permissions and access levels for users in the Cloud Foundry environment. They include roles such as admin, developer, and auditor. Roles can be managed through endpoints that allow for creation, updating, deletion, and retrieval of role details.

List roles

This endpoint lists roles that the user has access to.

Authorizations:
beareroauth
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:
beareroauth
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
{
  • "type": "organization_user",
  • "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"
}

Get a role

This endpoint gets an individual role resource.

Authorizations:
beareroauth
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
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a role

This endpoint deletes an individual role.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Root

The Root endpoint provides the entry point for the Cloud Foundry API. It includes links to all the available resources and endpoints. The Root endpoint can be accessed to retrieve detailed information about the Cloud Foundry API and its capabilities.

Get API root metadata

Returns the root-level metadata of the API, including links to all major service components. This endpoint serves as the main entry point for API discovery and navigation.

Responses

Response samples

Content type
application/json
{}

Get API root

Global API Root for Cloud Foundry V3.

Responses

Response samples

Content type
application/json
{}

Routes

Routes represent the network endpoints used to access apps in the Cloud Foundry environment. They include information such as domain, path, and port. Routes can be managed through endpoints that allow for creation, updating, deletion, and retrieval of route details. By specifying routes, applications can define how they are accessed by end-users, ensuring traffic is directed to the appropriate application instances.

List routes

Retrieve all routes the user has access to.

Authorizations:
beareroauth
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:
beareroauth
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.

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "path": "string",
  • "port": 0,
  • "relationships": {
    },
  • "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": {
    }
}

List destinations for a route

Retrieve all destinations associated with a route.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "destinations": [
    ]
}

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:
beareroauth
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
{
  • "pagination": {
    },
  • "destinations": [
    ]
}

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:
beareroauth
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
{
  • "pagination": {
    },
  • "destinations": [
    ]
}

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:
beareroauth
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
{
  • "pagination": {
    },
  • "destinations": [
    ]
}

Update a destination protocol for a route

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

Authorizations:
beareroauth
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": "http1"
}

Response samples

Content type
application/json
{
  • "guid": "string",
  • "app": {
    },
  • "weight": 0,
  • "port": 0,
  • "protocol": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "links": {
    }
}

Remove destination for a route

Remove a destination from a route.

Authorizations:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

List routes for an app

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

Authorizations:
beareroauth
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": [
    ],
  • "included": {
    }
}

Get a route

Retrieve a route.

Authorizations:
beareroauth
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": {
    }
}

Update a route

Update a route.

Authorizations:
beareroauth
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": {
    }
}

Delete a route

Delete a route.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

List shared spaces relationship

Lists the spaces that the route has been shared to.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

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:
beareroauth
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)

Responses

Request samples

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

Response samples

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

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

Unshares a route that was shared with another space.

Authorizations:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

SecurityGroups

SecurityGroups define the network access rules for apps in the Cloud Foundry environment. They include rules for inbound and outbound traffic. SecurityGroups can be managed through endpoints that allow for creation, updating, deletion, and retrieval of security group details.

List security groups

List security groups.

Authorizations:
beareroauth
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:
beareroauth
Request Body schema: application/json

Create a new security group with the provided rules.

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": "string",
  • "globally_enabled": {
    },
  • "rules": [
    ],
  • "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",
  • "globally_enabled": {
    },
  • "rules": [
    ],
  • "running_spaces": {
    },
  • "staging_spaces": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Get a security group

Get a security group.

Authorizations:
beareroauth
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",
  • "globally_enabled": {
    },
  • "rules": [
    ],
  • "running_spaces": {
    },
  • "staging_spaces": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Update a security group

Update a security group.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Update the security group properties such as name and rules.

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": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "globally_enabled": {
    },
  • "rules": [
    ],
  • "running_spaces": {
    },
  • "staging_spaces": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Delete a security group

Delete a security group.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Associate the security group with the given running spaces.

Array of objects (Relationship)

Responses

Request samples

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

Response samples

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

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:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Associate the security group with the given staging spaces.

Array of objects (Relationship)

Responses

Request samples

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

Response samples

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

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:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

ServiceBrokers

ServiceBrokers provide a way to manage and provision services in the Cloud Foundry environment. They include information such as service plans, instances, and bindings. ServiceBrokers can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service broker details.

List service brokers

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

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

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:
beareroauth
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": "string",
  • "url": "http://example.com",
  • "authentication": {
    },
  • "relationships": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Get a service broker

This endpoint retrieves the service broker by GUID.

Authorizations:
beareroauth
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",
  • "url": "http://example.com",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

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:
beareroauth
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": "string",
  • "url": "string",
  • "authentication": {
    },
  • "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",
  • "url": "http://example.com",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

ServiceCredentialBinding

ServiceCredentialBinding provides a way to bind service instances to apps in the Cloud Foundry environment. They include information such as credentials and bindings. ServiceCredentialBinding can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service credential binding details.

List service credential bindings

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

Authorizations:
beareroauth
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:
beareroauth
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
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": {
    }
}

Get a service credential binding

This endpoint retrieves the service credential binding by GUID.

Authorizations:
beareroauth
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:
beareroauth
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
{
  • "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": "app",
  • "name": "string",
  • "last_operation": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    },
  • "included": {
    }
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Get a service credential binding details

This endpoint retrieves the service credential binding details.

Authorizations:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{ }

ServiceInstances

ServiceInstances represent the instances of services in the Cloud Foundry environment. They include information such as service plans, bindings, and credentials. ServiceInstances can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service instance details.

List service instances

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

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

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:
beareroauth
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:
beareroauth
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:
beareroauth
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:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{ }

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{ }

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

List shared spaces relationship

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

Authorizations:
beareroauth
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
{
  • "data": [
    ]
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Share a service instance with additional spaces.

Array of objects (Relationship)

Responses

Request samples

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

Response samples

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

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

space_guid
required
string <uuid>

space_guid identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

ServiceOfferings

ServiceOfferings represent the available services in the Cloud Foundry environment. They include information such as service plans, instances, and bindings. ServiceOfferings can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service offering details.

List service offerings

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

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get a service offering

This endpoint retrieves the service offering by GUID.

Authorizations:
beareroauth
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",
  • "service_broker_guid": "string",
  • "service_broker_name": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Update a service offering

This endpoint updates a service offering with labels and annotations.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Update service offering properties such as metadata and documentation.

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_broker_guid": "string",
  • "service_broker_name": "string",
  • "metadata": {
    },
  • "links": {
    }
}

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:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

ServicePlans

ServicePlans define the configurations and pricing for services in the Cloud Foundry environment. They include information such as memory, instances, and routes. ServicePlans can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service plan details.

List service plans

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

Authorizations:
beareroauth
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:
beareroauth
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
{
  • "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": {
    }
}

Update a service plan

This endpoint updates a service plan with labels and annotations.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Update service plan properties such as metadata and maintenance info.

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Get a service plan visibility

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

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

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:
beareroauth
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:
beareroauth
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": "public",
  • "organizations": [
    ]
}

Response samples

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

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

organization_guid
required
string <uuid>

organization_guid identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

ServicePlanVisibility

ServicePlanVisibility defines the visibility and access rules for service plans in the Cloud Foundry environment. They include information such as organization and space access. ServicePlanVisibility can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service plan visibility details.

ServiceRouteBinding

ServiceRouteBinding provides a way to bind service instances to routes in the Cloud Foundry environment. They include information such as credentials and bindings. ServiceRouteBinding can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service route binding details.

List service route bindings

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

Authorizations:
beareroauth
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:
beareroauth
Request Body schema: application/json

Create a new service route binding between a service instance and a route.

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
{
  • "relationships": {
    },
  • "parameters": { },
  • "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",
  • "route_service_url": "http://example.com",
  • "last_operation": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    },
  • "included": {
    }
}

Get a service route binding

This endpoint retrieves the service route binding by GUID.

Authorizations:
beareroauth
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
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "route_service_url": "http://example.com",
  • "last_operation": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    },
  • "included": {
    }
}

Update a service route binding

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

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Update a service route binding, for example to change metadata.

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",
  • "route_service_url": "http://example.com",
  • "last_operation": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    },
  • "included": {
    }
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{ }

ServiceUsageEvents

ServiceUsageEvents track the usage and activity of services in the Cloud Foundry environment. They provide insights into service lifecycle changes, such as creation, deletion, and updates. ServiceUsageEvents are useful for monitoring and auditing purposes, helping administrators understand how services are being used and identify any issues. They can be retrieved through endpoints that provide detailed information about each event.

List service usage events

Retrieve all service usage events the user has access to.

Authorizations:
beareroauth
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:
beareroauth
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",
  • "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:
beareroauth

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Sidecars

Sidecars represent additional processes that run alongside the main app processes in the Cloud Foundry environment. They provide additional functionality, such as logging, monitoring, and security. Sidecars can be managed through endpoints that allow for creation, updating, deletion, and retrieval of sidecar details.

Get a sidecar

Get a sidecar.

Authorizations:
beareroauth
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",
  • "process_types": [
    ],
  • "memory_in_mb": 0,
  • "origin": "user",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Update a sidecar

Update a sidecar.

Authorizations:
beareroauth
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": "string",
  • "command": "string",
  • "process_types": [
    ],
  • "memory_in_mb": 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",
  • "name": "string",
  • "command": "string",
  • "process_types": [
    ],
  • "memory_in_mb": 0,
  • "origin": "user",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Delete a sidecar

Delete a sidecar.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

List sidecars for app

Retrieves all sidecars associated with a app.

Authorizations:
beareroauth
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:
beareroauth
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": "string",
  • "command": "string",
  • "process_types": [
    ],
  • "memory_in_mb": 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",
  • "name": "string",
  • "command": "string",
  • "process_types": [
    ],
  • "memory_in_mb": 0,
  • "origin": "user",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

List sidecars for process

Retrieves all sidecars associated with a process.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

SpaceFeatures

SpaceFeatures provide additional capabilities and configurations for spaces in the Cloud Foundry environment. These features can include things like auto-scaling, health checks, and custom domains. SpaceFeatures enhance the functionality of spaces by allowing administrators to enable or disable specific features based on their requirements. They can be managed through endpoints that allow for enabling, disabling, and retrieving the status of space features.

SpaceQuotas

SpaceQuotas define the resource limits and constraints for spaces in the Cloud Foundry environment. They include limits on memory, instances, routes, and services. SpaceQuotas can be managed through endpoints that allow for creation, updating, deletion, and retrieval of space quota details.

List space quotas

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

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a space quota

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

Authorizations:
beareroauth
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": "string",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "relationships": {
    },
  • "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",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Get a space quota

Get a space quota

Authorizations:
beareroauth
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",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

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:
beareroauth
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": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "apps": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    }
}

Delete a space quota

Space quotas cannot be deleted when applied to any spaces.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
path Parameters
quota_guid
required
string <uuid>

quota_guid identifier

Request Body schema: application/json

Apply the space quota to the given spaces.

Array of objects (Relationship)

Responses

Request samples

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

Response samples

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

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

space_guid
required
string <uuid>

space_guid identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Spaces

Spaces represent the logical grouping of resources within an organization in the Cloud Foundry environment. They provide a way to manage apps, services, and users within a specific context. Spaces can be managed through endpoints that allow for creation, updating, deletion, and retrieval of space details.

List spaces

Retrieve all spaces the user has access to.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ],
  • "included": {
    }
}

Create a space

Create a space.

Authorizations:
beareroauth
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": "string",
  • "relationships": {
    },
  • "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",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    },
  • "included": {
    }
}

Get a space

This endpoint retrieves the specified space object.

Authorizations:
beareroauth
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
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    },
  • "included": {
    }
}

Update a space

Update a space

Authorizations:
beareroauth
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": "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",
  • "relationships": {
    },
  • "links": {
    },
  • "metadata": {
    },
  • "included": {
    }
}

Delete a space

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

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/x-yaml

Provide an application manifest to apply to apps in the given space.

string

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

Get a space feature

Get a space feature

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

name
required
string
Value: "ssh"

name identifier

Responses

Response samples

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

Update a space feature

Update a space feature.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

name
required
string
Value: "ssh"

name identifier

Request Body schema: application/json

Update the named space feature, enabling or disabling it.

enabled
boolean

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/x-yaml

Provide a manifest to compare against the current space state and return a diff.

string

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

Get assigned isolation segment

Get assigned isolation segment

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Set or clear the isolation segment relationship for the space.

Relationship (object) or null

Responses

Request samples

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

Response samples

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

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:
beareroauth
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
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

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:
beareroauth
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:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

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

Stacks

Stacks are the base operating system and file system that your application will execute in. A stack is how you configure applications to run against different operating systems and different versions of those operating systems.

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

Stacks are not used for apps with a Docker lifecycle.

List stacks

Retrieve all stacks.

Authorizations:
beareroauth
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:
beareroauth
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:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Update stack metadata such as name and description.

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",
  • "description": "string",
  • "build_rootfs_image": "string",
  • "run_rootfs_image": "string",
  • "default": true,
  • "links": {
    },
  • "metadata": {
    }
}

Delete a stack

Delete a stack.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}

List apps on a stack

Retrieve all apps using a given stack.

Authorizations:
beareroauth
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
{
  • "pagination": {
    },
  • "resources": [
    ],
  • "included": {
    }
}

Tasks

Tasks represent one-off processes that can be run in the Cloud Foundry environment. They provide a way to execute background jobs, data migrations, and other tasks that are not part of the main app processes. Tasks can be managed through endpoints that allow for creation, updating, deletion, and retrieval of task details.

List tasks

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

Authorizations:
beareroauth
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:
beareroauth
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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Request Body schema: application/json

Update a task, for example to change its name or metadata.

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:
beareroauth
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:
beareroauth
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:
beareroauth
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:
beareroauth
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:
beareroauth
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
{
  • "command": "string",
  • "name": "string",
  • "memory_in_mb": 0,
  • "disk_in_mb": 0,
  • "log_rate_limit_in_bytes_per_second": 0,
  • "droplet_guid": "6b012c01-58eb-4697-a464-958715cd2e18",
  • "template": {
    },
  • "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": {
    }
}

Users

Users represent the individuals who have access to the Cloud Foundry environment. They include information such as roles, permissions, and credentials. Users can be managed through endpoints that allow for creation, updating, deletion, and retrieval of user details.

List users

Retrieve all users that the current user can see.

Authorizations:
beareroauth
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

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:
beareroauth
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
{
  • "guid": "string",
  • "username": "string",
  • "origin": "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",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Get a user

Retrieve a user.

Authorizations:
beareroauth
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",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": {
    }
}

Update a user

Update a user’s metadata.

Authorizations:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

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

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": {
    }
}

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",
  • "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:
beareroauth
path Parameters
guid
required
string <uuid>

The unique identifier for the resource

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "detail": "string",
  • "title": "string"
}