Cloud Foundry V3 API Operations Index
All available Cloud Foundry V3 API Operations
This endpoint will delete all of the existing buildpack caches in the blobstore. The buildpack cache is used during staging by buildpacks as a way to cache certain resources, e.g. downloaded Ruby gems. An admin who wants to decrease the size of their blobstore could use this endpoint to delete unnecessary blobs.
Retrieve all app usage events.
Retrieve a specific app usage event.
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.
Retrieve all apps the user has access to.
Creates a new app.
Retrieve a specific app.
Update an app.
Delete an app.
Start an app.
Stop 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.
Get the current droplet for an app.
This endpoint retrieves the current droplet relationship for an app.
Set the current droplet for an app. The current droplet is the droplet that the app will use when running.
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.
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.
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.
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.
This endpoint retrieves the list of features for the specified app.
Get an app feature.
Update an app feature.
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.
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.
Retrieve all audit events the user has access to.
Retrieve a specific audit event.
Retrieve all buildpacks.
Create a buildpack.
Retrieve a buildpack.
Update a buildpack.
Delete a buildpack.
Upload a zip file containing a Cloud Foundry compatible buildpack. The file must be sent as part of a multi-part form.
Retrieve all builds.
Create a build.
Retrieve a build.
Update a build.
Retrieve all builds for an app.
Update a build.
Retrieve all deployments.
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.
Retrieve a deployment.
Update a deployment.
Cancel a deployment.
Continue a deployment.
Retrieve all domains the user has access to.
Create a domain.
Retrieve a domain.
Update a domain.
Delete 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.
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.
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.
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.
Retrieve all droplets.
Retrieve a droplet.
Update a droplet.
Delete a droplet.
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.
Upload a gzip compressed tarball file containing a Cloud Foundry compatible droplet. The file must be sent as part of a multi-part form.
Retrieve an 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.
Retrieve all feature_flags.
Get a feature flag.
Update a feature flag.
Get information about the platform.
This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation.
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.
Create 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.
Update an isolation segment.
An isolation segment cannot be deleted if it is entitled to any organization.
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.
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.
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.
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.
Retrieve a specific job.
Retrieve all locks the user has access to.
Creates a new lock.
Retrieve a specific lock.
Update a lock
Delete a lock.
Generate a manifest for an app and its underlying processes.
This endpoint lists all organization quota resources.
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.
This endpoint gets an individual organization quota resource.
This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values.
Organization quotas cannot be deleted when applied to any organizations.
This endpoint applies an organization quota to one or more organizations.
Only admin users can apply an organization quota to an organization.
Retrieve all organizations the user has access to.
Create an organization.
This endpoint retrieves the specified organization object.
Update an organization.
When an organization is deleted, user roles associated with the organization will also be deleted.
Retrieve the default domain for a given organization.
This endpoint retrieves the specified organization object's memory and app instance usage summary.
Retrieve all users with a role in the specified organization.
Retrieve the default isolation segment for a given organization.
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.
Retrieve all packages.
Create a package.
Retrieve a package.
Update a package.
Delete a package.
Retrieve packages for an app that the user has access to.
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.
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.
Retrieve all processes.
Get a process.
Update a process.
Get stats for a process.
Scale a process.
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.
Retrieves all processes belonging to an app.
Get a specific process for an app.
Update a specific process for an app.
Get stats for a specific process for an app.
Scale a specific process for an app.
Terminate a specific process instance for an app.
Retrieve all registry credentials the user has access to. All users have read access to foundation-scoped registry credentials. All Org Users have read access to respective organization-scoped registry credentials. Users must have a Space specific role for read access to space-scoped registry credentials.
Create a registry credential.
Get a registry credential.
Update a registry credential.
Delete a registry credential.
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.
Retrieve a revision.
Update a revision.
Retrieve the environment variables that are associated with the revision.
Retrieve revisions for an app the user has access to.
Retrieve deployed revisions for an app the user has access to. Deployed revisions are revisions that are linked to started processes in the app.
This endpoint lists roles that the user has access to.
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.
This endpoint gets an individual role resource.
This endpoint deletes an individual role.
This endpoint returns links to the APIs available on a given Cloud Foundry deployment.
Returns the V3 API root endpoint information.
Retrieve all routes the user has access to.
Create a route.
Retrieve all destinations associated with a route.
Add one or more destinations to a route, preserving any existing destinations.
Weighted destinations (deprecated) cannot be added with this endpoint.
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.
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.
This endpoint updates the protocol of a route destination (app, port and weight cannot be updated)
Remove a destination from a route.
Retrieve all routes that have destinations that point to the given app.
Retrieve a route.
Update a route.
Delete a route.
Lists the spaces that the route has been shared to.
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.
Unshares a route that was shared with another space.
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.
List security groups.
Create a security group.
Get a security group.
Update a security group.
Delete a security group.
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.
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.
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.
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.
This endpoint retrieves the service brokers the user has access to.
This endpoint retrieves the service broker by GUID.
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.
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.
This endpoint retrieves the service credential bindings the user has access to.
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
This endpoint retrieves the service credential binding by GUID.
This endpoint updates a service credential binding with labels and annotations.
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.
This endpoint retrieves the service credential binding details.
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.
This endpoint retrieves the service instances the user has access to, including access granted by service instance sharing.
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
This endpoint retrieves the service instance by GUID.
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:
parametersservice_planmaintenance_infoname- when the service offering hasallow_context_updatesfeature enabled
Otherwise the response will be synchronous.
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.
Lists backups for a service instance. The service offering must support OSMAPI backup feature.
Creates a backup for a service instance. The service offering must support OSMAPI backup feature. This is an asynchronous operation that returns a job to poll for completion.
Restores a service instance from a backup. The service offering must support OSMAPI backup feature. This is an asynchronous operation that returns a job to poll for completion.
Retrieves the credentials for a user-provided service instance. This endpoint is not available for managed service instances.
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.
This endpoint lists the spaces that the service instance has been shared to.
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.
This endpoint returns the number of bound apps in spaces where the service instance has been shared to.
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.
This endpoint retrieves the service offerings the user has access to.
This endpoint retrieves the service offering by GUID.
This endpoint updates a service offering with labels and annotations.
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.
This endpoint retrieves JSON schemas for configuring service plan definitions across all service offerings. The schemas define the structure and validation rules for plan properties.
This endpoint is restricted to platform administrators and service administrators.
The endpoint attempts to fetch schemas from all service offerings. If a broker returns an error (including when the offering doesn't support plan definitions), the schema will be null but the offering is still included in the results.
This endpoint retrieves the plan definition schema for a specific service offering. The schema contains three components: a JSON schema (defining structure and validation rules), a UI schema (providing hints for rendering the configuration form), and a version string.
This endpoint is restricted to platform administrators and service administrators.
The endpoint attempts to fetch the schema from the broker. If the broker returns an error (including when the offering doesn't support plan definitions), the schema will be null.
This endpoint retrieves the service plans the user has access to.
This endpoint creates a new service plan with a custom definition. The service offering
must support the plan_definitions feature via OSMAPI. The plan is created by sending
the definition to the service broker, which then triggers a catalog sync to register
the plan in Cloud Foundry. This endpoint requires admin or service_admin role privileges.
The name and description fields must match between the top-level and the definition object.
This endpoint retrieves the service plan by GUID.
This endpoint updates a service plan with labels and annotations.
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.
This endpoint retrieves the service plan visibility for a given plan.
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.
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.
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).
This endpoint retrieves plan definitions for service plans. Only service plans from offerings that support plan definitions will have definition data populated. This endpoint requires admin privileges.
This endpoint retrieves the plan definition for a specific service plan by GUID. The definition contains the configuration properties and metadata for the plan. This endpoint requires admin privileges.
This endpoint updates the plan definition for a specific service plan. The entire definition is replaced with the provided values. After updating the definition, a catalog sync is triggered to ensure the service plan metadata is up to date. This endpoint requires admin privileges.
Note: The created_at and resource_version fields are read-only and managed by the broker.
This endpoint deletes the plan definition for a specific service plan. The service plan must not have any service instances associated with it. After deleting the definition, a catalog sync is triggered. This endpoint requires admin privileges.
This endpoint retrieves the service route bindings the user has access to.
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.
This endpoint retrieves the service route binding by GUID.
This endpoint updates a service route binding with labels and annotations.
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.
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.
Retrieve all service usage events the user has access to.
Retrieve a service usage event.
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.
Get a sidecar.
Update a sidecar.
Delete a sidecar.
Retrieves all sidecars associated with a app.
Create a sidecar associated with an app.
Retrieves all sidecars associated with a process.
This endpoint lists all space quota resources that the user has permission to view.
This endpoint creates a new space quota scoped to a specific organization.
Get a space quota
This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values.
Space quotas cannot be deleted when applied to any spaces.
This endpoint applies a space quota to one or more spaces.
Only an admin or an org manager in the quota’s parent organization can apply a space quota to a space.
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.
Retrieve all spaces the user has access to.
Create a space.
This endpoint retrieves the specified space object.
Update a space
When a space is deleted, the user roles associated with the space will be deleted.
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.
This endpoint retrieves the list of features for the specified space. Currently, the only feature on spaces is the SSH feature.
Get a space feature
Update a space feature.
Get assigned 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.
Deletes all routes in a space that are not mapped to any applications and not bound to any service instances.
This endpoint returns security groups that are enabled for running globally or at the space level for the given space.
This endpoint returns security groups that are enabled for staging globally or at the space level for the given space.
Retrieve all users with a role in the specified space.
Retrieve all stacks.
Create a stack.
Get a stack.
Update a stack.
Delete a stack.
Retrieve all apps using a given stack.
Retrieve all tasks the user has access to. The command field is excluded in the response.
Retrieve a task. The command field may be excluded in the response based on the user’s role.
Update 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.
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.
DEPRECATED - Use /v3/tasks/{guid}/actions/cancel instead.
Retrieve tasks for an app.
Create a task.
Retrieve all users that the current user can see.
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.
Retrieve a user.
Update a user's metadata.
All roles associated with a user will be deleted if the user is deleted.