openapi: 3.1.0 info: title: Cloud Foundry V3 API description: |- # Welcome to the Experimental Cloud Foundry V3 API Docs! # Expermiental Warning This OpenAPI specification is a experiment and not ready for productive use. # Getting help The CAPI team can most easily be reached on our Slack channel for questions and issues regarding the API. To report an issue with the docs or API, please feel free to file a GitHub issue on our API repo, cloud_controller_ng. We recommend reaching out to Slack first as we will be most responsive there. # More resources - The Cloud Foundry V2 API is still deprecated but still available for interacting with Cloud Foundry. - Running Tasks - V3 API Documentation OpenAPI Spec Source Code. version: latest license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html contact: name: Cloud Foundry url: https://www.cloudfoundry.org/ servers: - url: https://api.example.local description: Cloud Foundry V3 API server security: - oauth: - cloud_controller.read - cloud_controller.write tags: - name: Admin description: Administrative operations for Cloud Foundry platform management. - name: Apps description: Apps are top-level objects that link together and contain configuration information for your packages, droplets, processes, tasks, and more. - name: App Usage Events description: App usage events are a record of changes in the usage of apps and tasks. - name: Audit Events description: Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions. - name: Builds description: Builds represent the process of staging an application package. - name: Buildpacks description: Buildpacks are used during a build to download external dependencies and transform a package into an executable droplet. - name: Deployments description: Deployments are objects that manage updates to applications with zero downtime. - name: Domains description: Domains represent a fully qualified domain name that is used for application routes. - name: Droplets description: Droplets are the result of staging an application package. - name: Environment Variable Groups description: 'There are two types of environment variable groups: running and staging.' - name: Feature Flags description: Feature flags are runtime flags that enable or disable functionality on the API. - name: Info description: Info endpoints expose Cloud Controller configuration information. - name: Internal description: Internal endpoints for system monitoring and metrics. - name: Isolation Segments description: Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads. - name: Jobs description: Jobs are created by the platform when performing certain asynchronous actions. - name: Manifests description: A manifest is a method for applying bulk configurations to apps and their underlying processes. - name: Organizations description: An org is a development account that an individual or multiple collaborators can own and use. - name: Organization Quotas description: Organization quotas are named sets of memory, log rate, service, and instance usage quotas. - name: Packages description: A package is an application’s ‘source code’; either raw bits for your application or a pointer to these bits. - name: Processes description: Processes define the runnable units of an app. - name: Resource Matches description: Resource Matches are used to determine if a resource has been previously uploaded to the Cloud Controller. - name: Revisions description: Revisions represent code used by an application at a specific time. - name: Roles description: Roles are used to control access to resources. - name: Root description: Root API endpoints that provide entry points and API information. - name: Routes description: Routes are used to map a URL to an app. - name: Security Groups description: Security groups are used to control access to apps. - name: Service Brokers description: Service brokers are used to manage services. - name: Service Credential Bindings description: Service credential bindings are used to bind a service instance to an app. - name: Service Instances description: Service instances are instances of a service. - name: Service Offerings description: Service offerings are services that are available to be used. - name: Service Plans description: Service plans are plans for a service. - name: Service Route Bindings description: Service route bindings are used to bind a route to a service instance. - name: Service Usage Events description: Service usage events are a record of changes in the usage of services. - name: Sidecars description: Sidecars are used to run a process alongside an app. - name: Spaces description: Spaces are used to group apps and services. - name: Space Quotas description: Space quotas are named sets of memory, log rate, service, and instance usage quotas. - name: Stacks description: Stacks are used to specify the operating system and runtime environment for an app. - name: Tasks description: Tasks are one-off commands that can be run against an app. - name: Users description: Users are the users of the Cloud Foundry platform. paths: /: get: summary: Global API Root description: This endpoint returns links to the APIs available on a given Cloud Foundry deployment. operationId: getApiRoot tags: - Root responses: '200': description: OK content: application/json: schema: type: object properties: links: type: object description: Links to related resources properties: self: allOf: - $ref: '#/components/schemas/IndexLink' - description: Link to the current endpoint cloud_controller_v2: allOf: - $ref: '#/components/schemas/IndexLink' - description: Link to the Cloud Controller V2 API cloud_controller_v3: allOf: - $ref: '#/components/schemas/IndexLink' - description: Link to the Cloud Controller V3 API network_policy_v1: allOf: - $ref: '#/components/schemas/IndexLink' - description: Link to the Network Policy V1 API uaa: allOf: - $ref: '#/components/schemas/IndexLink' - description: Link to the UAA API logging: allOf: - $ref: '#/components/schemas/IndexLink' - description: Link to the Logging API log_cache: allOf: - $ref: '#/components/schemas/IndexLink' - description: Link to the Log Cache API log_stream: allOf: - $ref: '#/components/schemas/IndexLink' - description: Link to the Log Stream API '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/500' /v3: get: summary: Get V3 API root description: Returns the V3 API root endpoint information. operationId: getV3ApiRoot tags: - Root responses: '200': description: OK content: application/json: schema: type: object properties: links: type: object description: Links to related resources properties: self: allOf: - $ref: '#/components/schemas/Link' - description: Link to the current endpoint apps: allOf: - $ref: '#/components/schemas/Link' - description: Link to the apps endpoint builds: allOf: - $ref: '#/components/schemas/Link' - description: Link to the builds endpoint deployments: allOf: - $ref: '#/components/schemas/Link' - description: Link to the deployments endpoint domains: allOf: - $ref: '#/components/schemas/Link' - description: Link to the domains endpoint droplets: allOf: - $ref: '#/components/schemas/Link' - description: Link to the droplets endpoint feature_flags: allOf: - $ref: '#/components/schemas/Link' - description: Link to the feature flags endpoint info: allOf: - $ref: '#/components/schemas/Link' - description: Link to the info endpoint isolation_segments: allOf: - $ref: '#/components/schemas/Link' - description: Link to the isolation segments endpoint organizations: allOf: - $ref: '#/components/schemas/Link' - description: Link to the organizations endpoint packages: allOf: - $ref: '#/components/schemas/Link' - description: Link to the packages endpoint processes: allOf: - $ref: '#/components/schemas/Link' - description: Link to the processes endpoint roles: allOf: - $ref: '#/components/schemas/Link' - description: Link to the roles endpoint routes: allOf: - $ref: '#/components/schemas/Link' - description: Link to the routes endpoint security_groups: allOf: - $ref: '#/components/schemas/Link' - description: Link to the security groups endpoint service_brokers: allOf: - $ref: '#/components/schemas/Link' - description: Link to the service brokers endpoint service_instances: allOf: - $ref: '#/components/schemas/Link' - description: Link to the service instances endpoint service_offerings: allOf: - $ref: '#/components/schemas/Link' - description: Link to the service offerings endpoint service_plans: allOf: - $ref: '#/components/schemas/Link' - description: Link to the service plans endpoint spaces: allOf: - $ref: '#/components/schemas/Link' - description: Link to the spaces endpoint stacks: allOf: - $ref: '#/components/schemas/Link' - description: Link to the stacks endpoint tasks: allOf: - $ref: '#/components/schemas/Link' - description: Link to the tasks endpoint users: allOf: - $ref: '#/components/schemas/Link' - description: Link to the users endpoint '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/500' /v3/admin/actions/clear_buildpack_cache: post: summary: Clear the buildpack cache description: 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. operationId: clearBuildpackCache tags: - Admin responses: '202': description: Accepted headers: Location: description: URL of the job that is clearing the buildpack cache schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps: get: summary: List apps description: Retrieve all apps the user has access to. operationId: listApps tags: - Apps parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of app GUIDs to filter by - name: names in: query schema: type: array items: type: string description: Comma-delimited list of app names to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space GUIDs to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization GUIDs to filter by - name: stacks in: query schema: type: array items: type: string description: Comma-delimited list of stack names to filter by - name: lifecycle_type in: query schema: type: string enum: - buildpack - cnb - docker description: Lifecycle type to filter by - name: include in: query schema: type: array items: type: string enum: - space - space.organization description: Optionally include a list of unique related resources in the response responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-03-18T11:32:30Z' lifecycle: type: buildpack data: buildpacks: - java_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes packages: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages environment_variables: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables current_droplet: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current droplets: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets tasks: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks start: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start method: POST stop: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop method: POST revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions deployed_revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed features: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app2 state: STOPPED created_at: '1970-01-01T00:00:02Z' updated_at: '2016-06-08T16:41:26Z' lifecycle: type: buildpack data: buildpacks: - ruby_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes packages: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages environment_variables: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables current_droplet: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current droplets: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets tasks: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks start: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start method: POST stop: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop method: POST revisions: href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions deployed_revisions: href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed features: href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/features metadata: labels: {} annotations: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create an app description: Creates a new app. operationId: createApp tags: - Apps requestBody: $ref: '#/components/requestBodies/AppCreateRequestBody' responses: '201': description: Successfully created app content: application/json: schema: $ref: '#/components/schemas/App' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app state: STOPPED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-06-08T16:41:26Z' lifecycle: type: buildpack data: buildpacks: - java_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes packages: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages environment_variables: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables current_droplet: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current droplets: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets tasks: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks start: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start method: POST stop: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop method: POST revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions deployed_revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed features: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features metadata: labels: {} annotations: {} links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this app current_droplet: operationId: getDroplet parameters: guid: $response.body#/relationships/current_droplet/data/guid description: Retrieve the current droplet for this app '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Errors' examples: uniqueness_error: value: errors: - code: 10016 title: CF-UniquenessError detail: The given app name is already taken in the targeted space feature_disabled: value: errors: - code: 330002 title: CF-FeatureDisabled detail: Some feature flag must be enabled by the Cloud Foundry admin in order to push the app as is. '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/apps/{guid}: get: summary: Get an app description: Retrieve a specific app. operationId: getApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' - name: include in: query schema: type: array items: type: string enum: - space - space.organization description: Optionally include a list of unique related resources in the response responses: '200': description: Successfully retrieved app content: application/json: schema: $ref: '#/components/schemas/App' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app state: STOPPED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-06-08T16:41:26Z' lifecycle: type: buildpack data: buildpacks: - java_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes packages: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages environment_variables: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables current_droplet: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current droplets: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets tasks: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks start: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start method: POST stop: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop method: POST revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions deployed_revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed features: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features metadata: labels: {} annotations: {} links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this app current_droplet: operationId: getDroplet parameters: guid: $response.body#/relationships/current_droplet/data/guid description: Retrieve the current droplet for this app '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update an app description: Update an app. operationId: updateApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/AppUpdateRequestBody' responses: '200': description: Successfully updated app content: application/json: schema: $ref: '#/components/schemas/App' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-03-18T11:32:30Z' lifecycle: type: buildpack data: buildpacks: - java_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes packages: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages environment_variables: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables current_droplet: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current droplets: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets tasks: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks start: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start method: POST stop: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop method: POST revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions deployed_revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed features: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features metadata: labels: {} annotations: {} links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this app current_droplet: operationId: getDroplet parameters: guid: $response.body#/relationships/current_droplet/data/guid description: Retrieve the current droplet for this app '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete an app description: Delete an app. operationId: deleteApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Successfully deleted app headers: Location: description: URL of the job that is deleting the app schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/apps/{guid}/actions/start: post: summary: Start an app description: Start an app. operationId: startApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully started app content: application/json: schema: $ref: '#/components/schemas/App' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-03-18T11:32:30Z' lifecycle: type: buildpack data: buildpacks: - java_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes packages: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages environment_variables: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables current_droplet: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current droplets: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets tasks: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks start: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start method: POST stop: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop method: POST revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions deployed_revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed features: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features metadata: labels: {} annotations: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/actions/stop: post: summary: Stop an app description: Stop an app. operationId: stopApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully stopped app content: application/json: schema: $ref: '#/components/schemas/App' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-03-18T11:32:30Z' lifecycle: type: buildpack data: buildpacks: - java_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes packages: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages environment_variables: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables current_droplet: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current droplets: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets tasks: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks start: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start method: POST stop: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop method: POST revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions deployed_revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed features: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features metadata: labels: {} annotations: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/actions/restart: post: summary: Restart an app description: 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. operationId: restartApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully restarted app content: application/json: schema: $ref: '#/components/schemas/App' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-03-18T11:32:30Z' lifecycle: type: buildpack data: buildpacks: - java_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes packages: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages environment_variables: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables current_droplet: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current droplets: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets tasks: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks start: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start method: POST stop: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop method: POST revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions deployed_revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed features: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features metadata: labels: {} annotations: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/droplets: get: summary: List droplets for an app description: Retrieve all droplets belonging to an app. operationId: listAppDroplets tags: - Apps - Droplets parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of droplet guids to filter by - name: states in: query schema: type: array items: type: string enum: - AWAITING_UPLOAD - PROCESSING_UPLOAD - STAGED - COPYING - FAILED - EXPIRED description: Comma-delimited list of droplet states to filter by responses: '200': description: List of droplets for the app content: application/json: schema: $ref: '#/components/schemas/DropletList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org?page=1&per_page=50 last: href: https://api.example.org?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 state: STAGED error: null lifecycle: type: buildpack data: {} image: null execution_metadata: PRIVATE DATA HIDDEN process_types: redacted_message: 123e4567-e89b-12d3-a456-426614174000 checksum: type: sha256 value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 buildpacks: - name: ruby_buildpack detect_output: ruby 1.6.14 version: 1.1.1. buildpack_name: ruby stack: cflinuxfs4 created_at: '2016-03-28T23:39:34Z' updated_at: '2016-03-28T23:39:47Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 package: href: https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH download: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 state: STAGED error: null lifecycle: type: docker data: {} execution_metadata: 123e4567-e89b-12d3-a456-426614174000 process_types: redacted_message: 123e4567-e89b-12d3-a456-426614174000 image: cloudfoundry/diego-docker-app-custom:latest checksum: null buildpacks: null stack: null created_at: '2016-03-17T00:00:01Z' updated_at: '2016-03-17T21:41:32Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22 package: href: https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH metadata: labels: {} annotations: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/droplets/current: get: summary: Get current droplet description: Get the current droplet for an app. operationId: getCurrentDropletForApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully retrieved droplet content: application/json: schema: $ref: '#/components/schemas/Droplet' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 state: STAGED error: null lifecycle: type: buildpack data: {} execution_metadata: '' process_types: rake: bundle exec rake web: bundle exec rackup config.ru -p $PORT checksum: type: sha256 value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 buildpacks: - name: ruby_buildpack detect_output: ruby 1.6.14 version: 1.1.1. buildpack_name: ruby stack: cflinuxfs4 image: null created_at: '2016-03-28T23:39:34Z' updated_at: '2016-03-28T23:39:47Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 package: href: https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH download: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download metadata: labels: {} annotations: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/relationships/current_droplet: get: summary: Get current droplet association for an app description: This endpoint retrieves the current droplet relationship for an app. operationId: getCurrentDropletAssociationForApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet related: href: https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/droplets/current '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Set current droplet description: Set the current droplet for an app. The current droplet is the droplet that the app will use when running. operationId: setCurrentDropletForApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Droplet relationship object that needs to be set required: true content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Relationship' required: - data description: Request schema for setting the current droplet examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: Successfully set current droplet content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet related: href: https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/droplets/current '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/app_usage_events: get: summary: List app usage events description: Retrieve all app usage events. operationId: listAppUsageEvents tags: - App Usage Events parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: after_guid in: query schema: type: string description: Filters out events before and including the event with the given guid - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of usage event guids to filter by - $ref: '#/components/parameters/CreatedAts' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppUsageEventList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 2 first: href: https://api.example.org<%= path %>?page=1&per_page=1 last: href: https://api.example.org<%= path %>?page=2&per_page=1 next: href: https://api.example.org<%= path %>?page=2&per_page=1 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-05-28T16:41:23Z' updated_at: '2020-05-28T16:41:26Z' state: current: STARTED previous: STOPPED app: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1982 process: guid: 123e4567-e89b-12d3-a456-426614174000 type: type-1983 space: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1664 organization: guid: 123e4567-e89b-12d3-a456-426614174000 buildpack: guid: 123e4567-e89b-12d3-a456-426614174000 name: label-64 task: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-2929 memory_in_mb_per_instance: current: 512 previous: 256 instance_count: current: 10 previous: 5 links: self: href: https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/app_usage_events/{guid}: get: summary: Get an app usage event description: Retrieve a specific app usage event. operationId: getAppUsageEvent tags: - App Usage Events parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppUsageEvent' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-05-28T16:41:23Z' updated_at: '2020-05-28T16:41:26Z' state: current: STARTED previous: STOPPED app: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1982 process: guid: 123e4567-e89b-12d3-a456-426614174000 type: type-1983 space: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1664 organization: guid: 123e4567-e89b-12d3-a456-426614174000 buildpack: guid: 123e4567-e89b-12d3-a456-426614174000 name: label-64 task: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-2929 memory_in_mb_per_instance: current: 512 previous: 256 instance_count: current: 10 previous: 5 links: self: href: https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/app_usage_events/actions/destructively_purge_all_and_reseed: post: summary: Purge and seed app usage events description: |- 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. operationId: purgeAndSeedAppUsageEvents tags: - App Usage Events responses: '200': description: OK '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/audit_events: get: summary: List audit events description: Retrieve all audit events the user has access to. operationId: listAuditEvents tags: - Audit Events parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - name: types in: query schema: type: array items: type: string 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 description: Comma-delimited list of event types to filter by - name: target_guids in: query schema: type: array items: type: string description: Comma-delimited list of target guids to filter by. Also supports filtering by exclusion. - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuditEventList' examples: default: summary: default value: pagination: total_results: 1 total_pages: 1 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=1&per_page=2 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-06-08T16:41:23Z' updated_at: '2016-06-08T16:41:26Z' type: audit.app.update actor: guid: 123e4567-e89b-12d3-a456-426614174000 type: user name: admin target: guid: 123e4567-e89b-12d3-a456-426614174000 type: app name: my-app data: request: recursive: true space: guid: 123e4567-e89b-12d3-a456-426614174000 organization: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org//a595fe2f-01ff-4965-a50c-290258ab8582 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/audit_events/{guid}: get: summary: Get an audit event description: Retrieve a specific audit event. operationId: getAuditEvent tags: - Audit Events parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuditEvent' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-06-08T16:41:23Z' updated_at: '2016-06-08T16:41:26Z' type: audit.app.update actor: guid: 123e4567-e89b-12d3-a456-426614174000 type: user name: admin target: guid: 123e4567-e89b-12d3-a456-426614174000 type: app name: my-app data: request: recursive: true space: guid: 123e4567-e89b-12d3-a456-426614174000 organization: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/builds: get: summary: List builds description: Retrieve all builds. operationId: listBuilds tags: - Builds parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: states in: query schema: type: array items: type: string enum: - STAGING - STAGED - FAILED description: Comma-delimited list of build states to filter by - name: app_guids in: query schema: type: array items: type: string description: Comma-delimited list of app GUIDs to filter by - name: package_guids in: query schema: type: array items: type: string description: Comma-delimited list of package GUIDs to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/BuildList' examples: default: summary: default value: pagination: total_results: 1 total_pages: 1 first: href: https://api.example.org?states=STAGING&page=1&per_page=2 last: href: https://api.example.org?states=STAGING&page=1&per_page=2 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-03-28T23:39:34Z' updated_at: '2016-06-08T16:41:26Z' created_by: guid: 123e4567-e89b-12d3-a456-426614174000 name: bill email: bill@example.com state: STAGING staging_memory_in_mb: 1024 staging_disk_in_mb: 1024 staging_log_rate_limit_bytes_per_second: 1024 error: null lifecycle: type: buildpack data: buildpacks: - ruby_buildpack stack: cflinuxfs4 package: guid: 123e4567-e89b-12d3-a456-426614174000 droplet: null relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a build description: Create a build. operationId: createBuild tags: - Builds requestBody: description: Build object that needs to be created required: true content: application/json: schema: type: object properties: package: $ref: '#/components/schemas/Relationship' lifecycle: $ref: '#/components/schemas/Lifecycle' staging_memory_in_mb: type: integer description: Memory in MB allocated for staging of the build staging_disk_in_mb: type: integer description: Disk space in MB allocated for staging of the build staging_log_rate_limit_bytes_per_second: type: integer description: Log rate limit in bytes per second allocated for staging of the build metadata: $ref: '#/components/schemas/Metadata' required: - package description: Request schema for creating a build examples: default: summary: default value: package: guid: 123e4567-e89b-12d3-a456-426614174000 responses: '201': description: Successfully created build content: application/json: schema: $ref: '#/components/schemas/Build' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this build '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/builds/{guid}: get: summary: Get a build description: Retrieve a build. operationId: getBuild tags: - Builds parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully retrieved build content: application/json: schema: $ref: '#/components/schemas/Build' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this build droplet: operationId: getDroplet parameters: guid: $response.body#/droplet/guid description: Retrieve the droplet for this build '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a build description: Update a build. operationId: updateBuild tags: - Builds parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: $ref: '#/components/schemas/BuildUpdate' examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Build' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/buildpacks: get: summary: List buildpacks description: Retrieve all buildpacks. operationId: listBuildpacks tags: - Buildpacks parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: names in: query schema: type: array items: type: string description: | Comma-delimited list of buildpack names to filter by - name: stacks in: query schema: type: array items: type: string description: | Comma-delimited list of stacks to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/BuildpackList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org/v3/buildpacks?page=1&per_page=2 last: href: https://api.example.org/v3/buildpacks?page=2&per_page=2 next: href: https://api.example.org/v3/buildpacks?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-03-18T23:26:46Z' updated_at: '2016-10-17T20:00:42Z' name: my-buildpack state: AWAITING_UPLOAD filename: null stack: my-stack position: 1 lifecycle: cnb enabled: true locked: false metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 upload: href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload method: POST '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a buildpack description: Create a buildpack. operationId: createBuildpack tags: - Buildpacks requestBody: $ref: '#/components/requestBodies/BuildpackCreateRequestBody' responses: '201': $ref: '#/components/responses/BuildpackCreateResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/buildpacks/{guid}: get: summary: Get a buildpack description: Retrieve a buildpack. operationId: getBuildpack tags: - Buildpacks parameters: - $ref: '#/components/parameters/Guid' responses: '200': $ref: '#/components/responses/BuildpackGetResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a buildpack description: Update a buildpack. operationId: updateBuildpack tags: - Buildpacks parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/BuildpackUpdateRequestBody' responses: '200': description: Successfully updated buildpack content: application/json: schema: $ref: '#/components/schemas/Buildpack' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a buildpack description: Delete a buildpack. operationId: deleteBuildpack tags: - Buildpacks parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the buildpack schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/buildpacks/{guid}/upload: post: summary: Upload buildpack bits description: Upload a zip file containing a Cloud Foundry compatible buildpack. The file must be sent as part of a multi-part form. operationId: uploadBuildpack tags: - Buildpacks parameters: - $ref: '#/components/parameters/Guid' requestBody: description: The buildpack file to be uploaded required: true content: multipart/form-data: schema: type: object properties: bits: type: string format: binary resources: type: array items: type: object properties: path: type: string size_in_bytes: type: integer checksum: type: object properties: value: type: string responses: '200': description: Successfully uploaded buildpack content: application/json: schema: $ref: '#/components/schemas/Buildpack' '202': description: Upload initiated headers: Location: schema: type: string description: URL of the job tracking the upload content: application/json: schema: $ref: '#/components/schemas/Buildpack' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/deployments: get: summary: List deployments description: Retrieve all deployments. operationId: listDeployments tags: - Deployments parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: app_guids in: query schema: type: array items: type: string description: Comma-delimited list of app GUIDs to filter by - name: states in: query schema: type: array items: type: string description: Comma-delimited list of states to filter by - name: status_reasons in: query schema: type: array items: type: string enum: - DEPLOYING - PAUSED - CANCELING - DEPLOYED - CANCELED - SUPERSEDED description: Comma-delimited list of status reasons to filter by - name: status_values in: query schema: type: array items: type: string enum: - ACTIVE - FINALIZED description: Comma-delimited list of status values to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DeploymentList' examples: default: summary: default value: pagination: total_results: 1 total_pages: 1 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=1&per_page=2 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 status: value: FINALIZED reason: DEPLOYED details: last_successful_healthcheck: '2018-04-25T22:42:10Z' last_status_change: '2018-04-25T22:42:10Z' strategy: rolling options: max_in_flight: 1 droplet: guid: 123e4567-e89b-12d3-a456-426614174000 previous_droplet: guid: 123e4567-e89b-12d3-a456-426614174000 new_processes: - guid: 123e4567-e89b-12d3-a456-426614174000 type: web-deployment-59c3d133-2b83-46f3-960e-7765a129aea4 revision: guid: 123e4567-e89b-12d3-a456-426614174000 version: 1 created_at: '2018-04-25T22:42:10Z' updated_at: '2018-04-25T22:42:10Z' metadata: labels: {} annotations: {} relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4 app: href: https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a deployment description: 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. operationId: createDeployment tags: - Deployments requestBody: description: Deployment object that needs to be created required: true content: application/json: schema: type: object properties: relationships: $ref: '#/components/schemas/Relationships' strategy: type: string enum: - rolling - canary options: type: object properties: max_in_flight: type: integer description: The maximum number of instances that will be deployed simultaneously default: 1 minimum: 1 web_instances: type: integer description: The number of instances for the web process of the new droplet memory_in_mb: type: integer description: The amount of memory in megabytes to allocate for the web process disk_in_mb: type: integer description: The amount of disk space in megabytes to allocate for the web process log_rate_limit_in_bytes_per_second: type: integer description: The log rate limit in bytes per second for the web process. A value of -1 indicates unlimited, 0 prevents any logs from being emitted. canary: type: object description: Canary steps to use for the deployment. Only available for deployments with strategy ‘canary’. properties: steps: type: array description: Array of steps defining the canary deployment progression items: type: object properties: instance_weight: type: integer description: The percentage of instances to be deployed as part of the canary process in this step droplet: $ref: '#/components/schemas/Relationship' revision: $ref: '#/components/schemas/Relationship' metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: revision: guid: 123e4567-e89b-12d3-a456-426614174000 strategy: rolling relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 responses: '201': description: Successfully created deployment content: application/json: schema: $ref: '#/components/schemas/Deployment' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this deployment droplet: operationId: getDroplet parameters: guid: $response.body#/droplet/data/guid description: Retrieve the droplet for this deployment previous_droplet: operationId: getDroplet parameters: guid: $response.body#/previous_droplet/data/guid description: Retrieve the previous droplet for this deployment '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/deployments/{guid}: get: summary: Get a deployment description: Retrieve a deployment. operationId: getDeployment tags: - Deployments parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully retrieved deployment content: application/json: schema: $ref: '#/components/schemas/Deployment' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this deployment droplet: operationId: getDroplet parameters: guid: $response.body#/droplet/data/guid description: Retrieve the droplet for this deployment previous_droplet: operationId: getDroplet parameters: guid: $response.body#/previous_droplet/data/guid description: Retrieve the previous droplet for this deployment '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a deployment description: Update a deployment. operationId: updateDeployment tags: - Deployments parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Deployment object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a deployment examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': description: Successfully updated deployment content: application/json: schema: $ref: '#/components/schemas/Deployment' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/deployments/{guid}/actions/cancel: post: summary: Cancel a deployment description: Cancel a deployment. operationId: cancelDeployment tags: - Deployments parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully canceled deployment content: application/json: schema: $ref: '#/components/schemas/Deployment' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/deployments/{guid}/actions/continue: post: summary: Continue a deployment description: Continue a deployment. operationId: continueDeployment tags: - Deployments parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully continued deployment content: application/json: schema: $ref: '#/components/schemas/Deployment' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/domains: get: summary: List domains description: Retrieve all domains the user has access to. operationId: listDomains tags: - Domains parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of GUIDs to filter by - name: names in: query schema: type: array items: type: string description: Comma-delimited list of domain names to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of owning organization GUIDs to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DomainList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2019-03-08T01:06:19Z' updated_at: '2019-03-08T01:06:19Z' name: test-domain.com internal: false router_group: guid: 123e4567-e89b-12d3-a456-426614174000 supported_protocols: - tcp metadata: labels: {} annotations: {} relationships: organization: data: null shared_organizations: data: [] links: self: href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 route_reservations: href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations router_group: href: https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a domain description: Create a domain. operationId: createDomain tags: - Domains requestBody: $ref: '#/components/requestBodies/DomainCreateRequestBody' responses: '201': description: Successfully created domain content: application/json: schema: $ref: '#/components/schemas/Domain' links: organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this domain (private domains only) '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/domains/{guid}: get: summary: Get a domain description: Retrieve a domain. operationId: getDomain tags: - Domains parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully retrieved domain content: application/json: schema: $ref: '#/components/schemas/Domain' links: organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this domain (private domains only) '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a domain description: Update a domain. operationId: updateDomain tags: - Domains parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Domain object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a domain examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': description: Successfully updated domain content: application/json: schema: $ref: '#/components/schemas/Domain' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a domain description: Delete a domain. operationId: deleteDomain tags: - Domains parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the domain schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/domains/{guid}/relationships/shared_organizations: post: summary: Share a domain description: 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. operationId: shareDomain tags: - Domains parameters: - $ref: '#/components/parameters/Guid' requestBody: description: List of organizations to share the domain with required: true content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Relationship' description: Organization relationships; each organization will be entitled to manage this isolation segment examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: Successfully shared domain content: application/json: schema: type: object properties: data: type: array items: type: object properties: guid: type: string format: uuid examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/domains/{guid}/relationships/shared_organizations/{org_guid}: delete: summary: Unshare a domain description: 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. operationId: unshareDomain tags: - Domains parameters: - $ref: '#/components/parameters/Guid' - name: org_guid in: path required: true schema: type: string format: uuid description: The GUID of the organization to unshare the domain from responses: '204': description: Successfully unshared domain '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/droplets: get: summary: List droplets description: Retrieve all droplets. operationId: listDroplets tags: - Droplets parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: | Comma-delimited list of droplet GUIDs to filter by - name: states in: query schema: type: array items: type: string enum: - AWAITING_UPLOAD - PROCESSING_UPLOAD - STAGED - COPYING - FAILED - EXPIRED description: | Comma-delimited list of droplet states to filter by - name: app_guids in: query schema: type: array items: type: string description: | Comma-delimited list of app GUIDs to filter by - name: space_guids in: query schema: type: array items: type: string description: | Comma-delimited list of space GUIDs to filter by - name: organization_guids in: query schema: type: array items: type: string description: | Comma-delimited list of organization GUIDs to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DropletList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org?page=1&per_page=50 last: href: https://api.example.org?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 state: STAGED error: null lifecycle: type: buildpack data: {} image: null execution_metadata: PRIVATE DATA HIDDEN process_types: redacted_message: 123e4567-e89b-12d3-a456-426614174000 checksum: type: sha256 value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 buildpacks: - name: ruby_buildpack detect_output: ruby 1.6.14 version: 1.1.1. buildpack_name: ruby stack: cflinuxfs4 created_at: '2016-03-28T23:39:34Z' updated_at: '2016-03-28T23:39:47Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 package: href: https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH download: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 state: STAGED error: null lifecycle: type: docker data: {} execution_metadata: 123e4567-e89b-12d3-a456-426614174000 process_types: redacted_message: 123e4567-e89b-12d3-a456-426614174000 image: cloudfoundry/diego-docker-app-custom:latest checksum: null buildpacks: null stack: null created_at: '2016-03-17T00:00:01Z' updated_at: '2016-03-17T21:41:32Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22 package: href: https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH metadata: labels: {} annotations: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a droplet description: This endpoint is only for creating a droplet without a package. To create a droplet based on a package, see [Create a build](#create-a-build). operationId: createDroplet tags: - Droplets requestBody: $ref: '#/components/requestBodies/DropletCreateRequestBody' responses: '201': description: Droplet created content: application/json: schema: $ref: '#/components/schemas/Droplet' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 state: AWAITING_UPLOAD error: null lifecycle: type: buildpack data: {} execution_metadata: '' process_types: rake: bundle exec rake web: bundle exec rackup config.ru -p $PORT checksum: type: sha256 value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 buildpacks: - name: ruby_buildpack detect_output: ruby 1.6.14 version: 1.1.1. buildpack_name: ruby stack: cflinuxfs4 image: null created_at: '2016-03-28T23:39:34Z' updated_at: '2016-03-28T23:39:47Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH upload: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/upload method: POST metadata: labels: {} annotations: {} links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this droplet '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/droplets/{guid}: get: summary: Get a droplet description: Retrieve a droplet. operationId: getDroplet tags: - Droplets parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Droplet retrieved content: application/json: schema: $ref: '#/components/schemas/Droplet' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 state: STAGED error: null lifecycle: type: buildpack data: {} execution_metadata: '' process_types: rake: bundle exec rake web: bundle exec rackup config.ru -p $PORT checksum: type: sha256 value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 buildpacks: - name: ruby_buildpack detect_output: ruby 1.6.14 version: 1.1.1. buildpack_name: ruby stack: cflinuxfs4 image: null created_at: '2016-03-28T23:39:34Z' updated_at: '2016-03-28T23:39:47Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 package: href: https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH download: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download metadata: labels: {} annotations: {} links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this droplet '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a droplet description: Update a droplet. operationId: updateDroplet tags: - Droplets parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Droplet object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' image: type: string description: Image reference where the built complete image was stored required: [] description: Request schema for updating a droplet examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': $ref: '#/components/responses/DropletGetResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a droplet description: Delete a droplet. operationId: deleteDroplet tags: - Droplets parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the droplet schema: type: string format: uri content: application/json: schema: $ref: '#/components/schemas/Job' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/droplets/{guid}/download: get: summary: Download droplet bits description: |- 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. operationId: downloadDroplet tags: - Droplets parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/octet-stream: schema: type: string format: binary text/html: schema: type: string '302': description: Redirect to download location '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '502': $ref: '#/components/responses/BadGateway' /v3/droplets/{guid}/upload: post: summary: Upload droplet bits description: Upload a gzip compressed tarball file containing a Cloud Foundry compatible droplet. The file must be sent as part of a multi-part form. operationId: uploadDroplet tags: - Droplets parameters: - $ref: '#/components/parameters/Guid' requestBody: description: The droplet file to be uploaded required: true content: multipart/form-data: schema: type: object properties: bits: type: string format: binary resources: type: array items: type: object properties: path: type: string size_in_bytes: type: integer checksum: type: object properties: value: type: string application/json: schema: type: object properties: resources: type: array items: type: object properties: path: type: string size_in_bytes: type: integer checksum: type: object properties: value: type: string responses: '200': $ref: '#/components/responses/DropletGetResponse' '202': description: Upload initiated headers: Location: schema: type: string description: URL of the job tracking the upload content: application/json: schema: $ref: '#/components/schemas/Droplet' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/environment_variable_groups/{name}: get: summary: Get an environment variable group description: Retrieve an environment variable group. operationId: getEnvironmentVariableGroup tags: - Environment Variable Groups parameters: - name: name in: path required: true schema: type: string enum: - running - staging responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EnvironmentVariableGroup' examples: default: summary: default value: updated_at: '2016-05-04T17:00:41Z' name: running var: foo: bar links: self: href: https://api.example.org/v3/environment_variable_groups/running '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' patch: summary: Update environment variable group description: |- 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. operationId: updateEnvironmentVariableGroup tags: - Environment Variable Groups parameters: - name: name in: path required: true schema: type: string enum: - running - staging requestBody: description: The environment variables to update required: true content: application/json: schema: type: object properties: var: type: object additionalProperties: type: string description: Environment variables to inject; keys and values must be strings responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EnvironmentVariableGroup' examples: default: summary: default value: var: RAILS_ENV: production DEBUG: 'false' links: self: href: https://api.example.org/v3/environment_variable_groups/[name] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/feature_flags: get: summary: List feature flags description: Retrieve all feature_flags. operationId: listFeatureFlags tags: - Feature Flags parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: updated_ats in: query required: false schema: type: string description: | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FeatureFlagList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org/v3/feature_flags?page=1&per_page=2 last: href: https://api.example.org/v3/feature_flags?page=2&per_page=2 next: href: https://api.example.org/v3/feature_flags?page=2&per_page=2 previous: null resources: - name: my_feature_flag enabled: true updated_at: '2016-10-17T20:00:42Z' custom_error_message: error message the user sees links: self: href: https://api.example.org/v3/feature_flags/my_feature_flag - name: my_second_feature_flag enabled: false updated_at: null custom_error_message: null links: self: href: https://api.example.org/v3/feature_flags/my_second_feature_flag '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/feature_flags/{name}: get: summary: Get a feature flag description: Get a feature flag. operationId: getFeatureFlag tags: - Feature Flags parameters: - name: name in: path required: true schema: type: 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 description: The name of the feature flag responses: '200': description: Successfully retrieved feature flag content: application/json: schema: $ref: '#/components/schemas/FeatureFlag' examples: default: summary: default value: name: my_feature_flag enabled: true updated_at: '2016-10-17T20:00:42Z' custom_error_message: error message the user sees links: self: href: https://api.example.org/v3/feature_flags/my_feature_flag '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a feature flag description: Update a feature flag. operationId: updateFeatureFlag tags: - Feature Flags parameters: - name: name in: path required: true schema: type: 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 description: The name of the feature flag requestBody: description: Feature flag object that needs to be updated required: true content: application/json: schema: type: object properties: enabled: type: boolean description: Whether the feature flag is enabled custom_error_message: type: string description: The error string returned by the API when a client performs an action disabled by the feature flag examples: default: summary: default value: enabled: true custom_error_message: error message the user sees responses: '200': description: Successfully updated feature flag content: application/json: schema: $ref: '#/components/schemas/FeatureFlag' examples: default: summary: default value: name: my_feature_flag enabled: true updated_at: '2016-10-17T20:00:42Z' custom_error_message: error message the user sees links: self: href: https://api.example.org/v3/feature_flags/my_feature_flag '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/info: get: summary: Get platform info description: Get information about the platform. operationId: getPlatformInfo tags: - Info responses: '200': description: OK content: application/json: schema: type: object properties: name: type: string description: Name of the platform build: type: string description: Build number of the platform version: type: integer description: Version number of the platform description: type: string description: Description of the platform cli_version: type: object description: Minimum and recommended CLI versions properties: minimum: type: string description: Minimum CLI version recommended: type: string description: Recommended CLI version custom: type: object description: Custom information about the platform additionalProperties: type: string links: type: object description: Links to related resources properties: self: allOf: - $ref: '#/components/schemas/Link' - description: Link to the current endpoint support: allOf: - $ref: '#/components/schemas/Link' - description: Link to the support website for the platform examples: default: summary: default value: build: '' cli_version: minimum: '' recommended: '' custom: {} description: '' name: '' version: 0 osbapi_version: '' rate_limits: enabled: false general_limit: 2000 reset_interval_in_minutes: 30 links: self: href: http://api.example.com/v3/info support: href: '' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/info/usage_summary: get: summary: Get platform usage summary description: This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation. operationId: getPlatformUsageSummary tags: - Info responses: '200': description: OK content: application/json: schema: type: object properties: usage_summary: type: object description: Usage summary properties: started_instances: type: integer description: Total number of process instances in the STARTED state memory_in_mb: type: integer description: Sum of memory usage of all tasks in the RUNNING state and all process instances in the STARTED state routes: type: integer description: Total number of routes service_instances: type: integer description: Total number of managed service instances reserved_ports: type: integer description: Total number of reserved ports domains: type: integer description: Total number of private domains per_app_tasks: type: integer description: Total number of running tasks service_keys: type: integer description: Total number of service keys links: type: object description: Links to related resources properties: self: allOf: - $ref: '#/components/schemas/Link' - description: Link to the current endpoint examples: default: summary: default value: usage_summary: started_instances: 294 memory_in_mb: 123945 routes: 300 service_instances: 50 reserved_ports: 10 domains: 5 per_app_tasks: 0 service_keys: 20 links: self: href: http://api.example.com/v3/info/usage_summary '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/500' /v3/isolation_segments: get: summary: List isolation segments description: 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. operationId: listIsolationSegments tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of isolation segment guids to filter by. - name: names in: query schema: type: array items: type: string description: Comma-delimited list of isolation segment names to filter by. - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IsolationSegmentList' examples: default: summary: default value: pagination: total_results: 11 total_pages: 3 first: href: https://api.example.org/v3/isolation_segments?page=1&per_page=5 last: href: https://api.example.org/v3/isolation_segments?page=3&per_page=5 next: href: https://api.example.org/v3/isolation_segments?page=2&per_page=5 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 name: an_isolation_segment created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' links: self: href: https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c organizations: href: https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations metadata: annotations: {} labels: {} - guid: 123e4567-e89b-12d3-a456-426614174000 name: an_isolation_segment1 created_at: '2016-10-19T20:29:19Z' updated_at: '2016-11-08T16:41:26Z' links: self: href: https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac organizations: href: https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac/organizations metadata: annotations: {} labels: {} - guid: 123e4567-e89b-12d3-a456-426614174000 name: an_isolation_segment2 created_at: '2016-10-19T20:29:22Z' updated_at: '2016-11-08T16:41:26Z' links: self: href: https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03 organizations: href: https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03/organizations metadata: annotations: {} labels: {} - guid: 123e4567-e89b-12d3-a456-426614174000 name: an_isolation_segment3 created_at: '2016-10-19T20:29:27Z' updated_at: '2016-11-08T16:41:26Z' links: self: href: https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0 organizations: href: https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0/organizations metadata: annotations: {} labels: {} - guid: 123e4567-e89b-12d3-a456-426614174000 name: an_isolation_segment4 created_at: '2016-10-19T20:29:33Z' updated_at: '2016-11-08T16:41:26Z' links: self: href: https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7 organizations: href: https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7/organizations metadata: annotations: {} labels: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create an isolation segment description: Create an isolation segment. operationId: createIsolationSegment tags: - Isolation Segments requestBody: $ref: '#/components/requestBodies/IsolationSegmentCreate' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/IsolationSegment' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: an_isolation_segment created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' links: self: href: https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c organizations: href: https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations metadata: annotations: {} labels: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/isolation_segments/{guid}: get: summary: Get an isolation segment description: 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. operationId: getIsolationSegment tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IsolationSegment' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: an_isolation_segment created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' links: self: href: https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c organizations: href: https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations metadata: annotations: {} labels: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update an isolation segment description: Update an isolation segment. operationId: updateIsolationSegment tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Isolation segment to update required: true content: application/json: schema: type: object properties: name: type: string description: The name of the isolation segment metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: name: my_isolation_segment responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IsolationSegment' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: <%= name %> created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' links: self: href: https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c organizations: href: https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/organizations metadata: annotations: {} labels: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete an isolation segment description: An isolation segment cannot be deleted if it is entitled to any organization. operationId: deleteIsolationSegment tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Guid' responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/isolation_segments/{guid}/relationships/organizations: post: summary: Entitle organizations for isolation segment description: 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. operationId: entitleOrganizationsForIsolationSegment tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Guid' requestBody: description: List of organizations to entitle required: true content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations related: href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/organizations '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' get: summary: List organizations relationship description: 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. operationId: listOrganizationsForIsolationSegment tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations related: href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/organizations '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/isolation_segments/{guid}/relationships/organizations/{org_guid}: delete: summary: Revoke entitlement to isolation segment for an organization description: 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. operationId: revokeIsolationSegmentForOrganization tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Guid' - name: org_guid in: path required: true schema: type: string format: uuid description: The GUID of the organization to revoke entitlement from. responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/isolation_segments/{guid}/relationships/spaces: get: summary: List spaces relationship description: 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. operationId: listSpacesForIsolationSegment tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/isolation_segments/{guid}/organizations: get: summary: List organizations for isolation segment description: 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. operationId: listOrganizationsForIsolationSegmentShort tags: - Isolation Segments parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrganizationList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org/v3/isolation_segments/933b4c58-120b-499a-b85d-4b6fc9e2903b/organizations?page=1&per_page=50 last: href: https://api.example.org/v3/isolation_segments/933b4c58-120b-499a-b85d-4b6fc9e2903b/organizations?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: org1 suspended: false links: self: href: https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920 domains: href: https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains default_domain: href: https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains/default quota: href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d relationships: quota: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-02T00:14:30Z' updated_at: '2017-02-02T00:14:30Z' name: org2 suspended: false relationships: quota: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f domains: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains default_domain: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains/default quota: href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d metadata: labels: {} annotations: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/jobs/{guid}: get: summary: Get a job description: Retrieve a specific job. operationId: getJob tags: - Jobs parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully retrieved job content: application/json: schema: $ref: '#/components/schemas/Job' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' operation: app.delete state: FAILED links: self: href: https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 errors: - code: 10008 title: CF-UnprocessableEntity detail: something went wrong warnings: - detail: warning! warning! '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/resource_matches: post: summary: Create a resource match description: |- 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](#upload-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](#the-feature-flag-object) is disabled, resource matching will always return an empty array. operationId: postResourceMatches tags: - Resource Matches requestBody: content: application/json: schema: type: object properties: resources: type: array items: type: object properties: checksum: type: object properties: value: type: string size_in_bytes: type: integer path: type: string description: List of resources to check for in the resource cache required: - resources examples: default: summary: default value: resources: - checksum: value: 002d760bea1be268e27077412e11a320d0f164d3 size_in_bytes: 36 path: C:\path\to\file mode: '645' - checksum: value: a9993e364706816aba3e25717850c26c9cd0d89d size_in_bytes: 1 path: path/to/file mode: '644' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ResourceMatch' examples: default: summary: default value: resources: - checksum: value: a9993e364706816aba3e25717850c26c9cd0d89d size_in_bytes: 1 path: path/to/file mode: '644' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/revisions/{guid}: get: summary: Get a revision description: Retrieve a revision. operationId: getRevision tags: - Revisions parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully retrieved revision content: application/json: schema: $ref: '#/components/schemas/Revision' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this revision '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' patch: summary: Update a revision description: Update a revision. operationId: updateRevision tags: - Revisions parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Revision object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a revision examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': description: Successfully updated revision content: application/json: schema: $ref: '#/components/schemas/Revision' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this revision '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/revisions/{guid}/environment_variables: get: summary: Get environment variables for a revision description: Retrieve the environment variables that are associated with the revision. operationId: getRevisionEnvironmentVariables tags: - Revisions parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully retrieved revision environment variables content: application/json: schema: type: object properties: var: type: object description: Environment variables for the revision additionalProperties: type: string links: type: object properties: self: $ref: '#/components/schemas/Link' revision: $ref: '#/components/schemas/Link' app: $ref: '#/components/schemas/Link' examples: default: summary: default value: var: RAILS_ENV: production links: self: href: https://api.example.org/v3/revisions/[guid]/environment_variables revision: href: https://api.example.org/v3/revisions/[guid] app: href: https://api.example.org/v3/apps/[app_guid] '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/revisions: get: summary: List revisions for an app description: Retrieve revisions for an app the user has access to. operationId: listRevisionsForApp tags: - Revisions parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/LabelSelector' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - name: versions in: query schema: type: array items: type: string description: Comma-delimited list of revision versions to filter by responses: '200': description: Successfully retrieved revisions for app content: application/json: schema: $ref: '#/components/schemas/RevisionList' examples: default: summary: default value: pagination: total_results: 1 total_pages: 1 first: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50 last: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 version: 1 droplet: guid: 123e4567-e89b-12d3-a456-426614174000 processes: web: command: bundle exec rackup sidecars: - name: auth-sidecar command: bundle exec sidecar process_types: - web memory_in_mb: 300 description: Initial revision. deployable: true relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920 app: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 environment_variables: href: https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/revisions/deployed: get: summary: List deployed revisions for an app description: Retrieve deployed revisions for an app the user has access to. Deployed revisions are revisions that are linked to started processes in the app. operationId: listDeployedRevisionsForApp tags: - Revisions parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' responses: '200': description: Successfully retrieved deployed revisions for app content: application/json: schema: $ref: '#/components/schemas/RevisionList' examples: default: summary: default value: pagination: total_results: 1 total_pages: 1 first: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50 last: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 version: 1 droplet: guid: 123e4567-e89b-12d3-a456-426614174000 processes: web: command: bundle exec rackup sidecars: - name: auth-sidecar command: bundle exec sidecar process_types: - web memory_in_mb: 300 description: Initial revision. deployable: true relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920 app: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 environment_variables: href: https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/roles: get: summary: List roles description: This endpoint lists roles that the user has access to. operationId: listRoles tags: - Roles parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query description: Comma-delimited list of role guids to filter by schema: type: array items: type: string - name: types in: query description: Comma-delimited list of role types to filter by schema: type: array items: type: string enum: - organization_user - organization_auditor - organization_manager - organization_billing_manager - space_auditor - space_developer - space_manager - space_supporter - name: organization_guids in: query description: Comma-delimited list of organization guids to filter by schema: type: array items: type: string - name: space_guids in: query description: Comma-delimited list of space guids to filter by schema: type: array items: type: string - name: user_guids in: query description: Comma-delimited list of user guids to filter by schema: type: array items: type: string - name: include in: query description: Optionally include additional related resources in the response; valid values are `user`, `space`, and `organization`. schema: type: array items: type: string enum: - user - space - organization responses: '200': $ref: '#/components/responses/RoleListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a role description: |- 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. operationId: createRole tags: - Roles requestBody: $ref: '#/components/requestBodies/RoleCreate' responses: '201': description: Role created content: application/json: schema: $ref: '#/components/schemas/Role' examples: by_user_guid: summary: by user guid value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: guid: 123e4567-e89b-12d3-a456-426614174000 user_group: data: null organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 space: data: null links: self: href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 user: href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c by_username_and_origin: summary: by username and origin value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: guid: 123e4567-e89b-12d3-a456-426614174000 user_group: data: null organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 space: data: null links: self: href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 user: href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c links: user: operationId: getUser parameters: guid: $response.body#/relationships/user/data/guid description: Retrieve the user for this role organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this role (if organization role) space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this role (if space role) '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/roles/{guid}: get: summary: Get a role description: This endpoint gets an individual role resource. operationId: getRole tags: - Roles parameters: - $ref: '#/components/parameters/Guid' - name: include in: query description: Optionally include additional related resources in the response; valid values are `user`, `space`, and `organization`. schema: type: array items: type: string enum: - user - space - organization responses: '200': description: Role retrieved content: application/json: schema: $ref: '#/components/schemas/Role' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: guid: 123e4567-e89b-12d3-a456-426614174000 user_group: data: null organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 space: data: null links: self: href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 user: href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c links: user: operationId: getUser parameters: guid: $response.body#/relationships/user/data/guid description: Retrieve the user for this role organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this role (if organization role) space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this role (if space role) '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: summary: Delete a role description: This endpoint deletes an individual role. operationId: deleteRole tags: - Roles parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the role schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/routes: get: summary: List routes description: Retrieve all routes the user has access to. operationId: listRoutes tags: - Routes parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: protocols in: query schema: type: array items: type: string enum: - http - tcp description: Comma-delimited list of protocols to filter by - name: hosts in: query schema: type: array items: type: string description: Comma-delimited list of hosts to filter by - name: paths in: query schema: type: array items: type: string description: Comma-delimited list of paths to filter by - name: ports in: query schema: type: array items: type: integer description: Comma-delimited list of ports to filter by - name: domain_guids in: query schema: type: array items: type: string description: Comma-delimited list of domain GUIDs to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space GUIDs to filter by - name: app_guids in: query schema: type: array items: type: string description: Comma-delimited list of app GUIDs to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization GUIDs to filter by - name: service_instance_guids in: query schema: type: array items: type: string description: Comma-delimited list of service instance GUIDs to filter by - name: include in: query schema: type: array items: type: string enum: - domain - space.organization - space description: Optionally include a list of unique related resources in the response responses: '200': $ref: '#/components/responses/RouteListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a route description: Create a route. operationId: createRoute tags: - Routes requestBody: $ref: '#/components/requestBodies/RouteCreateRequestBody' responses: '201': description: Route created content: application/json: schema: $ref: '#/components/schemas/Route' links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this route domain: operationId: getDomain parameters: guid: $response.body#/relationships/domain/data/guid description: Retrieve the domain for this route '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/routes/{guid}/destinations: get: summary: List destinations for a route description: Retrieve all destinations associated with a route. operationId: listDestinationsForRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: List of destinations for the route content: application/json: schema: $ref: '#/components/schemas/RouteDestinationList' examples: default: summary: default value: destinations: - guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: web weight: null port: 8080 protocol: http2 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' - guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: api weight: null port: 9000 protocol: http1 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' links: self: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations route: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: summary: Insert destinations for a route description: |- Add one or more destinations to a route, preserving any existing destinations. Weighted destinations (deprecated) cannot be added with this endpoint. operationId: insertDestinationsForRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/RouteDestinations' responses: '200': description: List of destinations for the route content: application/json: schema: $ref: '#/components/schemas/RouteDestinationList' examples: default: summary: default value: destinations: - guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: web weight: null port: 8080 protocol: http2 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' - guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: api weight: null port: 9000 protocol: http1 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' links: self: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations route: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' patch: summary: Replace all destinations for a route description: |- 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. operationId: replaceDestinationsForRouteWithPatch tags: - Routes parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/RouteDestinations' responses: '200': description: List of destinations for the route content: application/json: schema: $ref: '#/components/schemas/RouteDestinationList' examples: default: summary: default value: destinations: - guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: web weight: 61 port: 8080 protocol: http2 - guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: api weight: 39 port: 9000 protocol: http1 links: self: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations route: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/routes/{guid}/destinations/{destination_guid}: patch: summary: Update a destination protocol for a route description: This endpoint updates the protocol of a route destination (app, port and weight cannot be updated) operationId: updateDestinationProtocolForRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' - name: destination_guid in: path required: true schema: type: string format: uuid description: The GUID of the route destination requestBody: description: Protocol of the destination required: true content: application/json: schema: type: object properties: protocol: type: string description: Protocol of the destination enum: - http1 - http2 required: - protocol examples: default: summary: default value: protocol: http2 responses: '200': description: Successfully updated protocol of the destination content: application/json: schema: $ref: '#/components/schemas/RouteDestination' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: web weight: 61 port: 8080 protocol: http2 links: destinations: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations route: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' delete: summary: Remove destination for a route description: Remove a destination from a route. operationId: removeDestinationForRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' - name: destination_guid in: path required: true schema: type: string format: uuid description: The GUID of the route destination to remove responses: '204': description: Successfully removed destination from the route '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/security_groups: get: summary: List security groups description: List security groups. operationId: listSecurityGroups tags: - Security Groups parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - name: guids in: query schema: type: array items: type: string description: Comma-separated list of resource GUIDs to filter by - name: names in: query schema: type: array items: type: string description: Comma-separated list of names to filter by (case insensitive) - name: globally_enabled_running in: query schema: type: boolean description: If true, only include the security groups that are enabled for running - name: globally_enabled_staging in: query schema: type: boolean description: If true, only include the security groups that are enabled for staging - name: running_space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: staging_space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SecurityGroupList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a security group description: Create a security group. operationId: createSecurityGroup tags: - Security Groups requestBody: content: application/json: schema: $ref: '#/components/schemas/SecurityGroupCreate' examples: default: summary: default value: name: my-group0 rules: - protocol: tcp destination: 10.10.10.0/24 ports: 443,80,8080 - protocol: icmp destination: 10.10.10.0/24 type: 8 code: 0 description: Allow ping requests to private services responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/SecurityGroup' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-02-20T17:42:08Z' updated_at: '2020-02-20T17:42:08Z' name: my-group0 globally_enabled: running: true staging: false rules: - protocol: tcp destination: 10.10.10.0/24 ports: 443,80,8080 - protocol: icmp destination: 10.10.10.0/24 type: 8 code: 0 description: Allow ping requests to private services - protocol: icmpv6 destination: '::/0' type: -1 code: -1 description: Allow all ICMPv6 traffic - protocol: tcp destination: 1.1.1.1,2.2.2.2/24,10.0.0.0-10.0.0.255 ports: 80,443,8080 description: Only valid if cc.security_groups.enable_comma_delimited_destinations is true relationships: staging_spaces: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 running_spaces: data: [] links: self: href: https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/security_groups/{guid}: get: summary: Get a security group description: Get a security group. operationId: getSecurityGroup tags: - Security Groups parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SecurityGroup' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-02-20T17:42:08Z' updated_at: '2020-02-20T17:42:08Z' name: my-group0 globally_enabled: running: true staging: false rules: - protocol: tcp destination: 10.10.10.0/24 ports: 443,80,8080 - protocol: icmp destination: 10.10.10.0/24 type: 8 code: 0 description: Allow ping requests to private services - protocol: icmpv6 destination: '::/0' type: -1 code: -1 description: Allow all ICMPv6 traffic - protocol: tcp destination: 1.1.1.1,2.2.2.2/24,10.0.0.0-10.0.0.255 ports: 80,443,8080 description: Only valid if cc.security_groups.enable_comma_delimited_destinations is true relationships: staging_spaces: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 running_spaces: data: [] links: self: href: https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a security group description: Update a security group. operationId: updateSecurityGroup tags: - Security Groups parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: $ref: '#/components/schemas/SecurityGroupUpdate' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SecurityGroup' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-02-20T17:42:08Z' updated_at: '2020-02-20T17:42:08Z' name: my-group0 globally_enabled: running: true staging: false rules: - protocol: tcp destination: 10.10.10.0/24 ports: 443,80,8080 - protocol: icmp destination: 10.10.10.0/24 type: 8 code: 0 description: Allow ping requests to private services - protocol: icmpv6 destination: '::/0' type: -1 code: -1 description: Allow all ICMPv6 traffic - protocol: tcp destination: 1.1.1.1,2.2.2.2/24,10.0.0.0-10.0.0.255 ports: 80,443,8080 description: Only valid if cc.security_groups.enable_comma_delimited_destinations is true relationships: staging_spaces: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 running_spaces: data: [] links: self: href: https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a security group description: Delete a security group. operationId: deleteSecurityGroup tags: - Security Groups parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the security group schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/500' /v3/security_groups/{guid}/relationships/running_spaces: post: summary: Bind a running security group to spaces description: 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. operationId: bindRunningSecurityGroup tags: - Security Groups parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/security_groups/{guid}/relationships/running_spaces/{space_guid}: delete: summary: Unbind a running security group from a space description: 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. operationId: unbindRunningSecurityGroup tags: - Security Groups parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/SpaceGuid' responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/security_groups/{guid}/relationships/staging_spaces: post: summary: Bind a staging security group to spaces description: 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. operationId: bindStagingSecurityGroup tags: - Security Groups parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/security_groups/{guid}/relationships/staging_spaces/{space_guid}: delete: summary: Unbind a staging security group from a space description: 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. operationId: unbindStagingSecurityGroup tags: - Security Groups parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/SpaceGuid' responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/service_brokers: get: summary: List service brokers description: This endpoint retrieves the service brokers the user has access to. operationId: listServiceBrokers tags: - Service Brokers parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: names in: query schema: type: array items: type: string description: Comma-delimited list of service broker names to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - $ref: '#/components/parameters/LabelSelector' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceBrokerList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 name: my_service_broker url: https://example.service-broker.com created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' relationships: {} metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_offerings: href: https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 - guid: 123e4567-e89b-12d3-a456-426614174000 name: another_service_broker url: https://another-example.service-broker.com created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_brokers/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62 service_offerings: href: https://api.example.org/v3/service_offerings?service_broker_guids=7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a service broker description: 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_](#service-broker-jobs) for more information and limitations. operationId: createServiceBroker tags: - Service Brokers requestBody: $ref: '#/components/requestBodies/ServiceBrokerCreate' responses: '202': description: Accepted headers: Location: description: URL of the job that is creating the service broker schema: type: string format: uri '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/service_brokers/{guid}: get: summary: Get a service broker description: This endpoint retrieves the service broker by GUID. operationId: getServiceBroker tags: - Service Brokers parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceBroker' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_service_broker url: https://example.service-broker.com created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: type: dev annotations: {} links: self: href: https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_offerings: href: https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this service broker (space-scoped brokers only) '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a service broker description: |- 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. operationId: updateServiceBroker tags: - Service Brokers parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/ServiceBrokerUpdateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceBroker' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_service_broker url: https://example.service-broker.com created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: type: dev annotations: {} links: self: href: https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_offerings: href: https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this service broker (space-scoped brokers only) '202': description: Accepted headers: Location: description: URL of the job that is updating the service broker schema: type: string format: uri '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a service broker description: This endpoint creates a job to delete an existing service broker. The `Location` header refers to the created job. See [_Service broker jobs_](#service-broker-jobs) for more information and limitations. operationId: deleteServiceBroker tags: - Service Brokers parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the service broker schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/service_credential_bindings: get: summary: List service credential bindings description: This endpoint retrieves the service credential bindings the user has access to. operationId: listServiceCredentialBindings tags: - Service Credential Bindings parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: names in: query schema: type: array items: type: string description: Comma-delimited list of service credential binding names to filter by - name: service_instance_guids in: query schema: type: array items: type: string description: Comma-delimited list of service instance guids to filter by - name: app_guids in: query schema: type: array items: type: string description: Comma-delimited list of app guids to filter by - name: type in: query schema: type: string enum: - app - key description: Type of credential binding to filter by. Valid values are 'app' or 'key' - name: service_instance_names in: query schema: type: array items: type: string description: Comma-delimited list of service instance names to filter by - name: app_names in: query schema: type: array items: type: string description: Comma-delimited list of app names to filter by - name: service_plan_guids in: query schema: type: array items: type: string description: Comma-delimited list of service plan guids to filter by - name: service_plan_names in: query schema: type: array items: type: string description: Comma-delimited list of service plan names to filter by - name: service_offering_guids in: query schema: type: array items: type: string description: Comma-delimited list of service offering guids to filter by - name: service_offering_names in: query schema: type: array items: type: string description: Comma-delimited list of service offering names to filter by - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of service credential binding guids to filter by - name: include in: query schema: type: array items: type: string enum: - app - service_instance description: 'Optionally include a list of unique related resources in the response. Valid values are: `app`, `service_instance`' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceCredentialBindingList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a service credential binding description: |- 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](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#orphan-mitigation) operationId: createServiceCredentialBinding tags: - Service Credential Bindings requestBody: $ref: '#/components/requestBodies/ServiceCredentialBindingCreateRequestBody' responses: '201': description: Created content: application/json: schema: oneOf: - $ref: '#/components/schemas/AppCredentialBinding' - $ref: '#/components/schemas/KeyCredentialBinding' discriminator: propertyName: type mapping: app: '#/components/schemas/AppCredentialBinding' key: '#/components/schemas/KeyCredentialBinding' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' name: some-name type: app last_operation: type: create state: succeeded created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' metadata: annotations: foo: bar labels: baz: qux relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 service_instance: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 details: href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details parameters: href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e app: href: https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13 '202': description: Accepted headers: Location: description: URL of the job that is creating the service credential binding schema: type: string format: uri '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/service_credential_bindings/{guid}: get: summary: Get a service credential binding description: This endpoint retrieves the service credential binding by GUID. operationId: getServiceCredentialBinding tags: - Service Credential Bindings parameters: - $ref: '#/components/parameters/Guid' - name: include in: query schema: type: array items: type: string enum: - app - service_instance description: Optionally include a list of unique related resources in the response responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/AppCredentialBinding' - $ref: '#/components/schemas/KeyCredentialBinding' discriminator: propertyName: type mapping: app: '#/components/schemas/AppCredentialBinding' key: '#/components/schemas/KeyCredentialBinding' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this credential binding (app bindings only) service_instance: operationId: getServiceInstance parameters: guid: $response.body#/relationships/service_instance/data/guid description: Retrieve the service instance for this credential binding '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a service credential binding description: This endpoint updates a service credential binding with labels and annotations. operationId: updateServiceCredentialBinding tags: - Service Credential Bindings parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/ServiceCredentialBindingUpdateRequestBody' responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/AppCredentialBinding' - $ref: '#/components/schemas/KeyCredentialBinding' discriminator: propertyName: type mapping: app: '#/components/schemas/AppCredentialBinding' key: '#/components/schemas/KeyCredentialBinding' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' name: some-name type: app last_operation: type: create state: succeeded created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' metadata: annotations: foo: bar labels: baz: qux relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 service_instance: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 details: href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details parameters: href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e app: href: https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a service credential binding description: 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. operationId: deleteServiceCredentialBinding tags: - Service Credential Bindings parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the service credential binding schema: type: string format: uri '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/service_credential_bindings/{guid}/details: get: summary: Get a service credential binding details description: This endpoint retrieves the service credential binding details. operationId: getServiceCredentialBindingDetails tags: - Service Credential Bindings parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/service_credential_bindings/{guid}/parameters: get: summary: Get parameters for a service credential binding description: 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](#the-service-offering-object) for the value of this feature flag. This endpoint is not available for User-Provided Service Instances. operationId: getServiceCredentialBindingParameters tags: - Service Credential Bindings parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object examples: default: summary: default value: foo: bar foz: baz '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/service_instances: get: summary: List service instances description: This endpoint retrieves the service instances the user has access to, including access granted by service instance sharing. operationId: listServiceInstances tags: - Service Instances parameters: - name: names in: query schema: type: array items: type: string description: Comma-delimited list of service instance names to filter by - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of service instance guids to filter by - name: type in: query schema: type: string enum: - managed - user-provided description: Filter by type; valid values are 'managed' and 'user-provided' - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by - name: service_plan_guids in: query schema: type: array items: type: string description: Comma-delimited list of service plan guids to filter by - name: service_plan_names in: query schema: type: array items: type: string description: Comma-delimited list of service plan names to filter by - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/LabelSelector' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - name: fields in: query schema: type: object description: Fields to include in the response responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/ServiceInstanceList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org/v3/service_instances?page=1&per_page=50 last: href: https://api.example.org/v3/service_instances?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-03-10T15:49:29Z' updated_at: '2020-03-10T15:49:29Z' name: my-managed-instance tags: [] type: managed maintenance_info: version: 1.0.0 upgrade_available: false dashboard_url: https://service-broker.example.org/dashboard broker_provided_metadata: labels: service_engine_version: '16.6' attributes: max_connections: '100' last_operation: type: create state: succeeded description: Operation succeeded updated_at: '2020-03-10T15:49:32Z' created_at: '2020-03-10T15:49:29Z' relationships: service_plan: data: guid: 123e4567-e89b-12d3-a456-426614174000 space: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c service_plan: href: https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac space: href: https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7 parameters: href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters shared_spaces: href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces service_credential_bindings: href: https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c service_route_bindings: href: https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-03-10T15:56:08Z' updated_at: '2020-03-10T15:56:08Z' name: my-user-provided-instance tags: - sql type: user-provided syslog_drain_url: http://logs.com route_service_url: https://routes.com last_operation: type: update state: succeeded description: Operation succeeded updated_at: '2020-03-10T15:59:32Z' created_at: '2020-03-10T15:59:29Z' relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133 space: href: https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7 credentials: href: https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials service_credential_bindings: href: https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133 service_route_bindings: href: https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a service instance description: |- 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](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#orphan-mitigation) operationId: createServiceInstance tags: - Service Instances requestBody: $ref: '#/components/requestBodies/ServiceInstanceCreateRequestBody' responses: '201': description: User Provided Service instance created content: application/json: schema: $ref: '#/components/schemas/UserProvidedServiceInstance' links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this service instance '202': description: Service instance creation in progress headers: Location: description: URL of the job that is creating the service instance schema: type: string format: uri '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/service_instances/{guid}: get: summary: Get a service instance description: This endpoint retrieves the service instance by GUID. operationId: getServiceInstance tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' - name: fields in: query schema: type: object description: Fields to include in the response responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedServiceInstance' - $ref: '#/components/schemas/UserProvidedServiceInstance' discriminator: propertyName: type mapping: managed: '#/components/schemas/ManagedServiceInstance' user-provided: '#/components/schemas/UserProvidedServiceInstance' links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this service instance service_plan: operationId: getServicePlan parameters: guid: $response.body#/relationships/service_plan/data/guid description: Retrieve the service plan for this service instance (managed instances only) '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a service instance description: |- 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. operationId: updateServiceInstance tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/ServiceInstanceUpdateRequestBody' responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedServiceInstance' - $ref: '#/components/schemas/UserProvidedServiceInstance' discriminator: propertyName: type mapping: managed: '#/components/schemas/ManagedServiceInstance' user-provided: '#/components/schemas/UserProvidedServiceInstance' links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this service instance service_plan: operationId: getServicePlan parameters: guid: $response.body#/relationships/service_plan/data/guid description: Retrieve the service plan for this service instance (managed instances only) '202': description: Accepted headers: Location: description: URL of the job that is updating the service instance schema: type: string format: uri '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a service instance description: |- 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. operationId: deleteServiceInstance tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' - name: purge in: query schema: type: boolean description: If `true`, deletes the service instance and all associated resources without any interaction with the service broker. responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the service instance schema: type: string format: uri '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/service_offerings: get: summary: List service offerings description: This endpoint retrieves the service offerings the user has access to. operationId: listServiceOfferings tags: - Service Offerings parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: names in: query schema: type: array items: type: string description: Comma-delimited list of service offering names to filter by - name: available in: query schema: type: boolean description: Filter by the `available` property; valid values are `true` or `false` - name: service_broker_guids in: query schema: type: array items: type: string description: Comma-delimited list of service broker GUIDs to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by - name: service_broker_names in: query schema: type: array items: type: string description: Comma-delimited list of service broker names to filter by - $ref: '#/components/parameters/LabelSelector' - name: fields in: query schema: type: object description: Fields to include in the response - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceOfferingList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 name: my_service_offering description: Provides my service available: true tags: - relational - caching requires: [] created_at: '2019-11-28T13:44:02Z' updated_at: '2019-11-28T13:44:02Z' shareable: true documentation_url: https://some-documentation-link.io broker_catalog: id: db730a8c-11e5-11ea-838a-0f4fff3b1cfb metadata: shareable: true features: plan_updateable: true bindable: true instances_retrievable: true bindings_retrievable: true allow_context_updates: false relationships: service_broker: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a service_plans: href: https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a service_broker: href: https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 - guid: 123e4567-e89b-12d3-a456-426614174000 name: other_service_offering description: Provides another service available: true tags: - caching requires: [] created_at: '2019-11-29T16:44:02Z' updated_at: '2019-11-29T16:44:02Z' shareable: true documentation_url: https://some-other-documentation-link.io broker_catalog: id: 3cb11822-12bb-11ea-beb1-a350dc7453b9 metadata: shareable: true features: plan_updateable: true bindable: true instances_retrievable: true bindings_retrievable: true allow_context_updates: false relationships: service_broker: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_offerings/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd service_plans: href: https://api.example.org/v3/service_plans?service_offering_guids=20e6cd62-12bb-11ea-90d1-7bfec2c75bcd service_broker: href: https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/service_offerings/{guid}: get: summary: Get a service offering description: This endpoint retrieves the service offering by GUID. operationId: getServiceOffering tags: - Service Offerings parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceOffering' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_service_offering description: Provides my service available: true tags: - relational - caching requires: [] created_at: '2019-11-28T13:44:02Z' updated_at: '2019-11-28T13:44:02Z' shareable: true documentation_url: https://some-documentation-link.io broker_catalog: id: db730a8c-11e5-11ea-838a-0f4fff3b1cfb metadata: shareable: true features: plan_updateable: true bindable: true instances_retrievable: true bindings_retrievable: true allow_context_updates: false relationships: service_broker: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a service_plans: href: https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a service_broker: href: https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a service offering description: This endpoint updates a service offering with labels and annotations. operationId: updateServiceOffering tags: - Service Offerings parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: properties: metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceOffering' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_service_offering description: Provides my service available: true tags: - relational - caching requires: [] created_at: '2019-11-28T13:44:02Z' updated_at: '2019-11-28T13:44:02Z' shareable: true documentation_url: https://some-documentation-link.io broker_catalog: id: db730a8c-11e5-11ea-838a-0f4fff3b1cfb metadata: shareable: true features: plan_updateable: true bindable: true instances_retrievable: true bindings_retrievable: true allow_context_updates: false relationships: service_broker: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_offerings/bf7eb420-11e5-11ea-b7db-4b5d5e7976a service_plans: href: https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a service_broker: href: https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a service offering description: |- 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. operationId: deleteServiceOffering tags: - Service Offerings parameters: - $ref: '#/components/parameters/Guid' - name: purge in: query schema: type: boolean description: If `true`, any service plans, instances, and bindings associated with this service offering will also be deleted responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/service_plans: get: summary: List service plans description: This endpoint retrieves the service plans the user has access to. operationId: listServicePlans tags: - Service Plans parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: names in: query schema: type: array items: type: string description: Comma-delimited list of service plan names to filter by - name: available in: query schema: type: boolean description: Filter by the `available` property; valid values are `true` or `false` - name: service_offering_guids in: query schema: type: array items: type: string description: Comma-delimited list of service offering guids to filter by - name: service_instance_guids in: query schema: type: array items: type: string description: Comma-delimited list of service instance guids to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by - name: broker_catalog_ids in: query schema: type: array items: type: string description: Comma-delimited list of broker catalog IDs to filter by - name: service_broker_guids in: query schema: type: array items: type: string description: Comma-delimited list of service broker GUIDs to filter by - name: service_broker_names in: query schema: type: array items: type: string description: Comma-delimited list of service broker names to filter by - name: service_offering_names in: query schema: type: array items: type: string description: Comma-delimited list of service offering names to filter by - name: include in: query schema: type: array items: type: string enum: - space.organization - service_offering description: Optionally include a list of unique related resources in the response - $ref: '#/components/parameters/LabelSelector' - name: fields in: query schema: type: object description: Fields to include in the response - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServicePlanList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/service_plans/{guid}: get: summary: Get a service plan description: This endpoint retrieves the service plan by GUID. operationId: getServicePlan tags: - Service Plans parameters: - $ref: '#/components/parameters/Guid' - name: include in: query schema: type: array items: type: string enum: - space.organization - service_offering description: Optionally include a list of unique related resources in the response responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServicePlan' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: my_big_service_plan description: Big visibility_type: public available: true free: false costs: - currency: USD amount: 199.99 unit: Monthly created_at: '2019-11-28T13:44:02Z' updated_at: '2019-11-28T13:44:02Z' maintenance_info: version: 1.0.0+dev4 description: Database version 7.8.0 broker_catalog: id: db730a8c-11e5-11ea-838a-0f4fff3b1cfb metadata: custom-key: custom-information maximum_polling_duration: null features: plan_updateable: true bindable: true schemas: service_instance: create: parameters: $schema: http://json-schema.org/draft-04/schema# type: object properties: billing-account: description: Billing account number used to charge use of shared fake server. type: string update: parameters: {} service_binding: create: parameters: {} relationships: service_offering: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 service_offering: href: https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 visibility: href: https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a service plan description: This endpoint updates a service plan with labels and annotations. operationId: updateServicePlan tags: - Service Plans parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: properties: metadata: $ref: '#/components/schemas/Metadata' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServicePlan' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a service plan description: |- 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. operationId: deleteServicePlan tags: - Service Plans parameters: - $ref: '#/components/parameters/Guid' responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/service_plans/{guid}/visibility: get: summary: Get a service plan visibility description: This endpoint retrieves the service plan visibility for a given plan. operationId: getServicePlanVisibility tags: - Service Plans parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServicePlanVisibility' examples: default: summary: default value: type: public '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a service plan visibility description: This endpoint updates a service plan visibility. It behaves similar to the [POST service plan visibility endpoint](#apply-a-service-plan-visibility) but this endpoint will replace the existing list of organizations when the service plan is `organization` visible. operationId: updateServicePlanVisibility tags: - Service Plans parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/ServicePlanVisibilityUpdateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServicePlanVisibility' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' post: summary: Apply a service plan visibility description: This endpoint applies a service plan visibility. It behaves similar to the [PATCH service plan visibility endpoint](#update-a-service-plan-visibility) but this endpoint will append to the existing list of organizations when the service plan is `organization` visible. operationId: applyServicePlanVisibility tags: - Service Plans parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/ServicePlanVisibilityCreateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServicePlanVisibility' examples: default: summary: default value: type: organization '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/service_plans/{guid}/visibility/{organization_guid}: delete: summary: Remove organization from a service plan visibility description: 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). operationId: removeOrganizationFromServicePlanVisibility tags: - Service Plans parameters: - $ref: '#/components/parameters/Guid' - name: organization_guid in: path required: true schema: type: string format: uuid responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/service_route_bindings: get: summary: List service route bindings description: This endpoint retrieves the service route bindings the user has access to. operationId: listServiceRouteBindings tags: - Service Route Bindings parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: route_guids in: query schema: type: array items: type: string description: Comma-delimited list of route guids to filter by - name: service_instance_guids in: query schema: type: array items: type: string description: Comma-delimited list of service instance guids to filter by - name: service_instance_names in: query schema: type: array items: type: string description: Comma-delimited list of service instance names to filter by - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of service route binding guids to filter by - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - name: include in: query schema: type: array items: type: string enum: - route - service_instance description: 'Optionally include a list of unique related resources in the response. Valid values are: `route`, `service_instance`' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceRouteBindingList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a service route binding description: |- 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. operationId: createServiceRouteBinding tags: - Service Route Bindings requestBody: content: application/json: schema: $ref: '#/components/schemas/ServiceRouteBindingCreate' examples: default: summary: default value: metadata: annotations: foo: bar labels: baz: qux relationships: route: data: guid: 123e4567-e89b-12d3-a456-426614174000 service_instance: data: guid: 123e4567-e89b-12d3-a456-426614174000 parameters: key1: value1 key2: value2 responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ServiceRouteBinding' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' route_service_url: https://route-service-url.io last_operation: type: create state: succeeded description: Operation succeeded updated_at: '2020-03-10T15:49:32Z' created_at: '2020-03-10T15:49:29Z' metadata: annotations: foo: bar labels: baz: qux relationships: service_instance: data: guid: 123e4567-e89b-12d3-a456-426614174000 route: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e route: href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13 parameters: href: https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters links: route: operationId: getRoute parameters: guid: $response.body#/relationships/route/data/guid description: Retrieve the route for this service route binding service_instance: operationId: getServiceInstance parameters: guid: $response.body#/relationships/service_instance/data/guid description: Retrieve the service instance for this service route binding '202': description: Accepted headers: Location: description: URL of the job that is creating the service route binding schema: type: string format: uri '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/service_route_bindings/{guid}: get: summary: Get a service route binding description: This endpoint retrieves the service route binding by GUID. operationId: getServiceRouteBinding tags: - Service Route Bindings parameters: - $ref: '#/components/parameters/Guid' - name: include in: query schema: type: array items: type: string enum: - route - service_instance description: Optionally include a list of unique related resources in the response responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceRouteBinding' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' route_service_url: https://route-service-url.io last_operation: type: create state: succeeded description: Operation succeeded updated_at: '2020-03-10T15:49:32Z' created_at: '2020-03-10T15:49:29Z' metadata: annotations: foo: bar labels: baz: qux relationships: service_instance: data: guid: 123e4567-e89b-12d3-a456-426614174000 route: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e route: href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13 parameters: href: https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters links: route: operationId: getRoute parameters: guid: $response.body#/relationships/route/data/guid description: Retrieve the route for this service route binding service_instance: operationId: getServiceInstance parameters: guid: $response.body#/relationships/service_instance/data/guid description: Retrieve the service instance for this service route binding '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a service route binding description: This endpoint updates a service route binding with labels and annotations. operationId: updateServiceRouteBinding tags: - Service Route Bindings parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: properties: metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceRouteBinding' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' route_service_url: https://route-service-url.io last_operation: type: create state: succeeded description: Operation succeeded updated_at: '2020-03-10T15:49:32Z' created_at: '2020-03-10T15:49:29Z' metadata: annotations: foo: bar labels: baz: qux relationships: service_instance: data: guid: 123e4567-e89b-12d3-a456-426614174000 route: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e route: href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13 parameters: href: https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a service route binding description: 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. operationId: deleteServiceRouteBinding tags: - Service Route Bindings parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the service route binding schema: type: string format: uri '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/service_route_bindings/{guid}/parameters: get: summary: Get parameters for a route binding description: 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](#the-service-offering-object) for the value of this feature flag. This endpoint is not available for User-Provided Service Instances. operationId: getServiceRouteBindingParameters tags: - Service Route Bindings parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object examples: default: summary: default value: foo: bar foz: baz '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/service_usage_events: get: summary: List service usage events description: Retrieve all service usage events the user has access to. operationId: listServiceUsageEvents tags: - Service Usage Events parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - name: after_guid in: query description: Filters out events before and including the event with the given guid. schema: type: string - name: guids in: query description: Comma-delimited list of usage event guids to filter by. schema: type: array items: type: string - name: service_instance_types in: query description: Comma-delimited list of service instance types to filter by; valid values are `managed_service_instance` and `user_provided_service_instance` schema: type: array items: type: string enum: - managed_service_instance - user_provided_service_instance - name: service_offering_guids in: query description: Comma-delimited list of service offering guids to filter by schema: type: array items: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceUsageEventList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 2 first: href: https://api.example.org<%= path %>?page=1&per_page=1 last: href: https://api.example.org<%= path %>?page=2&per_page=1 next: href: https://api.example.org<%= path %>?page=2&per_page=1 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-05-28T12:34:56Z' updated_at: '2020-05-28T12:34:56Z' state: CREATED space: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1664 organization: guid: 123e4567-e89b-12d3-a456-426614174000 service_instance: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1982 type: managed_service_instance service_plan: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1983 service_offering: guid: 123e4567-e89b-12d3-a456-426614174000 name: label-64 service_broker: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-2929 links: self: href: https://api.example.org/v3/service_usage_events/c9976002-96f4-435a-888e-db1e1178df62 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/service_usage_events/{guid}: get: summary: Get a service usage event description: Retrieve a service usage event. operationId: getServiceUsageEvent tags: - Service Usage Events parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceUsageEvent' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2020-05-28T12:34:56Z' updated_at: '2020-05-28T12:34:56Z' state: CREATED space: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1664 organization: guid: 123e4567-e89b-12d3-a456-426614174000 service_instance: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1982 type: managed_service_instance service_plan: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-1983 service_offering: guid: 123e4567-e89b-12d3-a456-426614174000 name: label-64 service_broker: guid: 123e4567-e89b-12d3-a456-426614174000 name: name-2929 links: self: href: https://api.example.org/v3/service_usage_events/c9976002-96f4-435a-888e-db1e1178df62 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/service_usage_events/actions/destructively_purge_all_and_reseed: post: summary: Purge and seed service usage events description: 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. operationId: purgeAndSeedServiceUsageEvents tags: - Service Usage Events responses: '200': description: OK '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/sidecars/{guid}: get: summary: Get a sidecar description: Get a sidecar. operationId: getSidecar tags: - Sidecars parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Sidecar' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: auth-sidecar command: bundle exec rackup process_types: - web - worker memory_in_mb: 300 origin: user relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this sidecar '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' patch: summary: Update a sidecar description: Update a sidecar. operationId: updateSidecar tags: - Sidecars parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/SidecarUpdateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Sidecar' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: auth-sidecar command: bundle exec rackup process_types: - web - worker memory_in_mb: 300 origin: user relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this sidecar '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a sidecar description: Delete a sidecar. operationId: deleteSidecar tags: - Sidecars parameters: - $ref: '#/components/parameters/Guid' responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/apps/{guid}/sidecars: get: summary: List sidecars for app description: Retrieves all sidecars associated with a app. operationId: listAppSidecars tags: - Sidecars parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SidecarList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 name: auth-sidecar command: bundle exec rackup process_types: - web - worker memory_in_mb: 300 origin: user relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' - guid: 123e4567-e89b-12d3-a456-426614174000 name: echo-sidecar command: start-echo-server process_types: - web memory_in_mb: 300 origin: user relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:59Z' updated_at: '2017-02-01T01:33:59Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: summary: Create a sidecar associated with an app description: Create a sidecar associated with an app. operationId: createSidecar tags: - Sidecars parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/SidecarCreate' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Sidecar' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 name: auth-sidecar command: bundle exec rackup process_types: - web - worker memory_in_mb: 300 origin: user relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this sidecar '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/spaces: get: summary: List spaces description: Retrieve all spaces the user has access to. operationId: listSpaces tags: - Spaces parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: names in: query schema: type: array items: type: string description: Comma-delimited list of space names to filter by - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by - name: include in: query schema: type: array items: type: string enum: - organization description: Optionally include a list of unique related resources in the response responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SpaceList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org/v3/spaces?page=1&per_page=50 last: href: https://api.example.org/v3/spaces?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: space1 relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 quota: data: null links: self: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920 features: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features organization: href: https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133 apply_manifest: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest method: POST metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-02T00:14:30Z' updated_at: '2017-02-02T00:14:30Z' name: space2 relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 quota: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f features: href: https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/features organization: href: https://api.example.org/v3/organizations/b4ce91bd-31df-4b7d-8fd4-21a6b533276b quota: href: https://api.example.org/v3/space_quotas/6da62599-4890-4a08-8b6f-180a4f47e46b apply_manifest: href: https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9/actions/apply_manifest method: POST metadata: labels: {} annotations: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a space description: Create a space. operationId: createSpace tags: - Spaces requestBody: $ref: '#/components/requestBodies/SpaceCreateRequestBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Space' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-space relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 quota: data: null links: self: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920 features: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features organization: href: https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133 apply_manifest: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest method: POST metadata: labels: {} annotations: {} links: organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this space quota: operationId: getSpaceQuota parameters: guid: $response.body#/relationships/quota/data/guid description: Retrieve the quota associated with this space '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/spaces/{guid}: get: summary: Get a space description: This endpoint retrieves the specified space object. operationId: getSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' - name: include in: query schema: type: array items: type: string enum: - organization description: Optionally include additional related resources in the response responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Space' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-space relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 quota: data: null links: self: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920 features: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features organization: href: https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133 apply_manifest: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest method: POST metadata: labels: {} annotations: {} links: organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this space quota: operationId: getSpaceQuota parameters: guid: $response.body#/relationships/quota/data/guid description: Retrieve the quota associated with this space '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a space description: Update a space operationId: updateSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/SpaceUpdateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Space' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-space relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 quota: data: null links: self: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920 features: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/features organization: href: https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133 apply_manifest: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/actions/apply_manifest method: POST metadata: labels: {} annotations: {} links: organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this space quota: operationId: getSpaceQuota parameters: guid: $response.body#/relationships/quota/data/guid description: Retrieve the quota associated with this space '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a space description: When a space is deleted, the user roles associated with the space will be deleted. operationId: deleteSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: location: description: URL of the job to query the asynchronous operation schema: type: string format: uri '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/spaces/{guid}/actions/apply_manifest: post: summary: Apply a manifest to a space description: |- 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. operationId: applyManifestToSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/x-yaml: schema: type: string responses: '202': description: Accepted headers: Location: description: URL of the job that is applying the manifest schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/spaces/{guid}/features: get: summary: List space features description: This endpoint retrieves the list of features for the specified space. Currently, the only feature on spaces is the SSH feature. operationId: listSpaceFeatures tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SpaceFeature' examples: default: summary: default value: resources: - name: ssh description: Enable SSHing into apps in the space. enabled: true - name: diego_docker description: Allow Docker image support for the space. enabled: false '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/spaces/{guid}/features/{name}: get: summary: Get a space feature description: Get a space feature operationId: getSpaceFeature tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' - name: name in: path required: true schema: type: string enum: - ssh responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SpaceFeature' examples: default: summary: default value: name: ssh description: Enable SSHing into apps in the space. enabled: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a space feature description: Update a space feature. operationId: updateSpaceFeature tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' - name: name in: path required: true schema: type: string enum: - ssh requestBody: content: application/json: schema: properties: enabled: type: boolean examples: default: summary: default value: enabled: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SpaceFeature' examples: default: summary: default value: name: ssh description: Enable SSHing into apps in the space. enabled: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/spaces/{guid}/manifest_diff: post: summary: Create a manifest diff for a space (experimental) description: |- 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](#the-manifest-schema) manifests. operationId: createManifestDiffForSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/x-yaml: schema: type: string responses: '201': description: Accepted headers: Location: description: URL of the job that is creating the manifest diff schema: type: string format: uri '202': description: Accepted headers: Location: description: URL of the job that is creating the manifest diff schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/spaces/{guid}/relationships/isolation_segment: get: summary: Get assigned isolation segment description: Get assigned isolation segment operationId: getAssignedIsolationSegmentForSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment related: href: https://api.example.org/v3/isolation_segments/e4c91047-3b29-4fda-b7f9-04033e5a9c9f '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Manage isolation segment description: |- This endpoint assigns an isolation segment to the space. The isolation segment must be [entitled](#entitle-organizations-for-an-isolation-segment) to the space’s parent organization. Apps will not run in the newly assigned isolation segment until they are restarted. operationId: manageIsolationSegmentForSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment related: href: https://api.example.org/v3/isolation_segments/e4c91047-3b29-4fda-b7f9-04033e5a9c9f '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/spaces/{guid}/routes: delete: summary: Delete unmapped routes for a space description: Deletes all routes in a space that are not mapped to any applications and not bound to any service instances. operationId: deleteUnmappedRoutesForSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' - name: unmapped in: query required: true schema: type: boolean enum: - true description: Filter to only delete unmapped routes responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting unmapped routes schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/spaces/{guid}/usage_summary: get: summary: Get usage summary for a space description: This endpoint retrieves the specified space's memory and app instance usage summary. operationId: getUsageSummaryForSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object properties: usage_summary: type: object properties: started_instances: type: integer memory_in_mb: type: integer routes: type: integer service_instances: type: integer reserved_ports: type: integer domains: type: integer per_app_tasks: type: integer service_keys: type: integer links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this usage summary space: $ref: '#/components/schemas/Link' description: The URL to get the space for this usage summary examples: default: summary: default value: usage_summary: started_instances: 3 memory_in_mb: 3072 routes: 3 service_instances: 2 reserved_ports: 1 domains: 1 per_app_tasks: 0 service_keys: 1 links: self: href: https://api.example.org/v3/spaces/f47ac10b-58cc-4372-a567-0e02b2c3d479/usage_summary organization: href: https://api.example.org/v3/spaces/f47ac10b-58cc-4372-a567-0e02b2c3d479 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/spaces/{guid}/running_security_groups: get: summary: List running security groups for a space description: This endpoint returns security groups that are enabled for running globally or at the space level for the given space. operationId: listRunningSecurityGroupsForSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SecurityGroupList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/spaces/{guid}/staging_security_groups: get: summary: List staging security groups for a space description: This endpoint returns security groups that are enabled for staging globally or at the space level for the given space. operationId: listStagingSecurityGroupsForSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SecurityGroupList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/spaces/{guid}/users: get: summary: List users for a space description: Retrieve all users with a role in the specified space. operationId: listUsersForSpace tags: - Spaces parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/space_quotas: get: summary: List space quotas description: This endpoint lists all space quota resources that the user has permission to view. operationId: listSpaceQuotas tags: - Space Quotas parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of space quota guids to filter by - name: names in: query schema: type: array items: type: string description: Comma-delimited list of space quota names to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SpaceQuotaList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org/v3/space_quotas?page=1&per_page=50 last: href: https://api.example.org/v3/space_quotas?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote apps: total_memory_in_mb: 5120 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 10 per_app_tasks: null services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 20 relationships: organizations: data: guid: 123e4567-e89b-12d3-a456-426614174000 spaces: data: - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301 organization: href: https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104 - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-05-04T17:00:41Z' updated_at: '2017-05-04T17:00:41Z' name: sancho-panza apps: total_memory_in_mb: 2048 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 5 per_app_tasks: 2 services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 4 relationships: organizations: data: guid: 123e4567-e89b-12d3-a456-426614174000 spaces: data: [] links: self: href: https://api.example.org/v3/space_quotas/554bcf32-7032-4cb0-92bc-738f9d2089d3 organization: href: https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a space quota description: This endpoint creates a new space quota scoped to a specific organization. operationId: createSpaceQuota tags: - Space Quotas requestBody: $ref: '#/components/requestBodies/SpaceQuotaCreate' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/SpaceQuota' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote apps: total_memory_in_mb: 5120 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 10 per_app_tasks: null services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 20 relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 spaces: data: - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301 organization: href: https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104 links: organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this space quota '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/space_quotas/{guid}: get: summary: Get a space quota description: Get a space quota operationId: getSpaceQuota tags: - Space Quotas parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SpaceQuota' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote apps: total_memory_in_mb: 5120 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 10 per_app_tasks: null services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 20 relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 spaces: data: - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301 organization: href: https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104 links: organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this space quota '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a space quota description: This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values. operationId: updateSpaceQuota tags: - Space Quotas parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/SpaceQuotaUpdate' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SpaceQuota' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote apps: total_memory_in_mb: 5120 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 10 per_app_tasks: null services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 20 relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 spaces: data: - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301 organization: href: https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104 links: organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this space quota '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a space quota description: Space quotas cannot be deleted when applied to any spaces. operationId: deleteSpaceQuota tags: - Space Quotas parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the space quota schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/space_quotas/{quota_guid}/relationships/spaces: post: summary: Apply a space quota to a space description: |- 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. operationId: applySpaceQuota tags: - Space Quotas parameters: - name: quota_guid in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/space_quotas/quota-guid/relationships/spaces '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/space_quotas/{guid}/relationships/spaces/{space_guid}: delete: summary: Remove a space quota from a space description: |- 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. operationId: removeSpaceQuotaFromSpace tags: - Space Quotas parameters: - $ref: '#/components/parameters/Guid' - name: space_guid in: path required: true schema: type: string format: uuid responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/stacks: get: summary: List stacks description: Retrieve all stacks. operationId: listStacks tags: - Stacks parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: names in: query schema: type: array items: type: string description: Comma-delimited list of stack names to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StackList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2018-11-09T22:43:28Z' updated_at: '2018-11-09T22:43:28Z' name: my-stack-1 build_rootfs_image: my-stack-1-build run_rootfs_image: my-stack-1-run description: This is my first stack! state: ACTIVE state_reason: null default: true metadata: labels: {} annotations: {} links: self: href: https://api.example.org/11c916c9-c2f9-440e-8e73-102e79c4704d - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2018-11-09T22:43:29Z' updated_at: '2018-11-09T22:43:29Z' name: my-stack-2 description: This is my second stack! build_rootfs_image: my-stack-2-build run_rootfs_image: my-stack-2-run state: DEPRECATED state_reason: Stack deprecated and will be removed in future release default: false metadata: labels: {} annotations: {} links: self: href: https://api.example.org/81c916c9-c2f9-440e-8e73-102e79c4704h '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a stack description: Create a stack. operationId: createStack tags: - Stacks requestBody: $ref: '#/components/requestBodies/StackCreateRequestBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Stack' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/stacks/{guid}: get: summary: Get a stack description: Get a stack. operationId: getStack tags: - Stacks parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Stack' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a stack description: Update a stack. operationId: updateStack tags: - Stacks parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: properties: metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information state: ACTIVE state_reason: Optional plain text describing the stack state change responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Stack' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a stack description: Delete a stack. operationId: deleteStack tags: - Stacks parameters: - $ref: '#/components/parameters/Guid' responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/stacks/{guid}/apps: get: summary: List apps on a stack description: Retrieve all apps using a given stack. operationId: listAppsOnStack tags: - Stacks parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-03-18T11:32:30Z' lifecycle: type: buildpack data: buildpacks: - java_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes packages: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages environment_variables: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables current_droplet: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current droplets: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets tasks: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks start: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/start method: POST stop: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/actions/stop method: POST revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions deployed_revisions: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed features: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/features metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 name: my_app2 state: STOPPED created_at: '1970-01-01T00:00:02Z' updated_at: '2016-06-08T16:41:26Z' lifecycle: type: buildpack data: buildpacks: - ruby_buildpack stack: cflinuxfs4 relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes packages: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages environment_variables: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables current_droplet: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current droplets: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets tasks: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks start: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start method: POST stop: href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop method: POST revisions: href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions deployed_revisions: href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed features: href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/features metadata: labels: {} annotations: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/tasks: get: summary: List tasks description: Retrieve all tasks the user has access to. The `command` field is excluded in the response. operationId: listTasks tags: - Tasks parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of task guids to filter by - name: names in: query schema: type: array items: type: string description: Comma-delimited list of task names to filter by - name: states in: query schema: type: array items: type: string enum: - PENDING - RUNNING - SUCCEEDED - CANCELING - FAILED description: Comma-delimited list of task states to filter by - name: app_guids in: query schema: type: array items: type: string description: Comma-delimited list of app guids to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by - name: sequence_ids in: query schema: type: array items: type: integer description: Comma-delimited list of sequence ids to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TaskList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/tasks/{guid}: get: summary: Get a task description: Retrieve a task. The `command` field may be excluded in the response based on the user’s role. operationId: getTask tags: - Tasks parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Task' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this task droplet: operationId: getDroplet parameters: guid: $response.body#/droplet_guid description: Retrieve the droplet for this task '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a task description: Update a task. operationId: updateTask tags: - Tasks parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: properties: metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Task' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/tasks/{guid}/actions/cancel: post: summary: Cancel a task description: 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. operationId: cancelTask tags: - Tasks parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: OK content: application/json: schema: $ref: '#/components/schemas/Task' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' put: summary: Cancel a task (PUT) description: 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. operationId: cancelTaskPut tags: - Tasks parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: OK content: application/json: schema: $ref: '#/components/schemas/Task' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/tasks/{guid}/cancel: put: summary: DEPRECATED - Cancel a task (short path) description: DEPRECATED - Use /v3/tasks/{guid}/actions/cancel instead. operationId: cancelTaskShort tags: - Tasks parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: OK content: application/json: schema: $ref: '#/components/schemas/Task' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/users: get: summary: List users description: Retrieve all users that the current user can see. operationId: listUsers tags: - Users parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of user guids to filter by (can include UAA user IDs or client IDs) - name: usernames in: query schema: type: array items: type: string description: Comma-delimited list of usernames to filter by - name: origins in: query schema: type: array items: type: string description: Comma-delimited list of user origins to filter by - name: partial_usernames in: query schema: type: array items: type: string description: Comma-delimited list of partial usernames to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a user description: |- 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. operationId: createUser tags: - Users requestBody: $ref: '#/components/requestBodies/UserCreate' responses: '201': $ref: '#/components/responses/UserCreateResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/users/{guid}: get: summary: Get a user description: Retrieve a user. operationId: getUser tags: - Users parameters: - $ref: '#/components/parameters/UserGuid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a user description: Update a user's metadata. operationId: updateUser tags: - Users parameters: - $ref: '#/components/parameters/UserGuid' requestBody: $ref: '#/components/requestBodies/UserUpdate' responses: '200': $ref: '#/components/responses/UserUpdateResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a user description: All roles associated with a user will be deleted if the user is deleted. operationId: deleteUser tags: - Users parameters: - $ref: '#/components/parameters/UserGuid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the user schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/organizations: get: summary: List organizations description: Retrieve all organizations the user has access to. operationId: listOrganizations tags: - Organizations parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: names in: query schema: type: array items: type: string description: Comma-delimited list of organization names to filter by - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrganizationList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org/v3/organizations?page=1&per_page=50 last: href: https://api.example.org/v3/organizations?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: org1 suspended: false relationships: quota: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920 domains: href: https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains default_domain: href: https://api.example.org/v3/organizations/885735b5-aea4-4cf5-8e44-961af0e41920/domains/default quota: href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-02T00:14:30Z' updated_at: '2017-02-02T00:14:30Z' name: org2 suspended: false relationships: quota: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f domains: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains default_domain: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/domains/default quota: href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d metadata: labels: {} annotations: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create an organization description: Create an organization. operationId: createOrganization tags: - Organizations requestBody: $ref: '#/components/requestBodies/OrganizationCreateRequestBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Organization' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-organization suspended: false relationships: quota: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52 domains: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains default_domain: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default quota: href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d metadata: labels: {} annotations: {} links: quota: operationId: getOrganizationQuota parameters: guid: $response.body#/relationships/quota/data/guid description: Retrieve the quota associated with this organization '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/organizations/{guid}: get: summary: Get an organization description: This endpoint retrieves the specified organization object. operationId: getOrganization tags: - Organizations parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Organization' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-organization suspended: false relationships: quota: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52 domains: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains default_domain: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default quota: href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d metadata: labels: {} annotations: {} links: quota: operationId: getOrganizationQuota parameters: guid: $response.body#/relationships/quota/data/guid description: Retrieve the quota associated with this organization '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update an organization description: Update an organization. operationId: updateOrganization tags: - Organizations parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/OrganizationUpdateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Organization' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-organization suspended: false relationships: quota: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52 domains: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains default_domain: href: https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52/domains/default quota: href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d metadata: labels: {} annotations: {} links: quota: operationId: getOrganizationQuota parameters: guid: $response.body#/relationships/quota/data/guid description: Retrieve the quota associated with this organization '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete an organization description: When an organization is deleted, user roles associated with the organization will also be deleted. operationId: deleteOrganization tags: - Organizations parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: location: description: URL of the job to query the asynchronous operation schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/organizations/{guid}/domains/default: get: summary: Get default domain description: Retrieve the default domain for a given organization. operationId: getDefaultDomainForOrganization tags: - Organizations parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Domain' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/organizations/{guid}/usage_summary: get: summary: Get usage summary description: This endpoint retrieves the specified organization object's memory and app instance usage summary. operationId: getUsageSummaryForOrganization tags: - Organizations parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object properties: usage_summary: type: object properties: started_instances: type: integer memory_in_mb: type: integer routes: type: integer service_instances: type: integer reserved_ports: type: integer domains: type: integer per_app_tasks: type: integer service_keys: type: integer links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this usage summary organization: $ref: '#/components/schemas/Link' description: The URL to get the organization for this usage summary examples: default: summary: default value: usage_summary: started_instances: 3 memory_in_mb: 50 routes: 4 service_instances: 2 reserved_ports: 1 domains: 4 per_app_tasks: 2 service_keys: 1 links: self: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/usage_summary organization: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/organizations/{guid}/users: get: summary: List users for an organization description: Retrieve all users with a role in the specified organization. operationId: listUsersForOrganization tags: - Organizations parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of user guids to filter by - name: usernames in: query schema: type: array items: type: string description: Comma-delimited list of usernames to filter by - name: origins in: query schema: type: array items: type: string description: Comma-delimited list of user origins to filter by - name: partial_usernames in: query schema: type: array items: type: string description: Comma-delimited list of partial usernames to filter by - $ref: '#/components/parameters/LabelSelector' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/organizations/{guid}/relationships/default_isolation_segment: get: summary: Get default isolation segment description: Retrieve the default isolation segment for a given organization. operationId: getDefaultIsolationSegmentForOrganization tags: - Organizations parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment related: href: https://api.example.org/v3/isolation_segments/9d8e007c-ce52-4ea7-8a57-f2825d2c6b39 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Assign default isolation segment description: |- 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. operationId: assignDefaultIsolationSegmentForOrganization tags: - Organizations parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' examples: default: summary: default value: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment related: href: https://api.example.org/v3/isolation_segments/9d8e007c-ce52-4ea7-8a57-f2825d2c6b39 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/organization_quotas: get: summary: List organization quotas description: This endpoint lists all organization quota resources. operationId: listOrganizationQuotas tags: - Organization Quotas parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of organization quota guids to filter by - name: names in: query schema: type: array items: type: string description: Comma-delimited list of organization quota names to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrganizationQuotaList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org/v3/organization_quotas?page=1&per_page=50 last: href: https://api.example.org/v3/organization_quotas?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote apps: total_memory_in_mb: 5120 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 10 per_app_tasks: 5 services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 4 domains: total_domains: 7 relationships: organizations: data: - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organization_quotas/quota-1-guid - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-05-04T17:00:41Z' updated_at: '2017-05-04T17:00:41Z' name: sancho-panza apps: total_memory_in_mb: 2048 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 5 per_app_tasks: 2 services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 4 domains: total_domains: 7 relationships: organizations: data: [] links: self: href: https://api.example.org/v3/organization_quotas/quota-2-guid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create an organization quota description: |- 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. operationId: createOrganizationQuota tags: - Organization Quotas requestBody: $ref: '#/components/requestBodies/OrganizationQuotaCreateRequestBody' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/OrganizationQuota' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote apps: total_memory_in_mb: 5120 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 10 per_app_tasks: 5 services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 4 domains: total_domains: 7 relationships: organizations: data: - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organization_quotas/quota-guid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/organization_quotas/{guid}: get: summary: Get an organization quota description: This endpoint gets an individual organization quota resource. operationId: getOrganizationQuota tags: - Organization Quotas parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrganizationQuota' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote apps: total_memory_in_mb: 5120 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 10 per_app_tasks: 5 services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 4 domains: total_domains: 7 relationships: organizations: data: - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organization_quotas/quota-guid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update an organization quota description: This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values. operationId: updateOrganizationQuota tags: - Organization Quotas parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/OrganizationQuotaUpdateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrganizationQuota' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote apps: total_memory_in_mb: 5120 per_process_memory_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 total_instances: 10 per_app_tasks: 5 services: paid_services_allowed: true total_service_instances: 10 total_service_keys: 20 routes: total_routes: 8 total_reserved_ports: 4 domains: total_domains: 7 relationships: organizations: data: - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organization_quotas/quota-guid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete an organization quota description: Organization quotas cannot be deleted when applied to any organizations. operationId: deleteOrganizationQuota tags: - Organization Quotas parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the organization quota schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/organization_quotas/{quota_guid}/relationships/organizations: post: summary: Apply an organization quota to an organization description: |- This endpoint applies an organization quota to one or more organizations. Only admin users can apply an organization quota to an organization. operationId: applyOrganizationQuota tags: - Organization Quotas parameters: - name: quota_guid in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/organization_quotas/quota-guid/relationships/organizations '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/packages: get: summary: List packages description: Retrieve all packages. operationId: listPackages tags: - Packages parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of package guids to filter by - name: states in: query schema: type: array items: type: string enum: - AWAITING_UPLOAD - PROCESSING_UPLOAD - READY - FAILED - COPYING - EXPIRED description: Comma-delimited list of package states to filter by - name: types in: query schema: type: array items: type: string enum: - bits - docker description: Comma-delimited list of package types to filter by - name: app_guids in: query schema: type: array items: type: string description: Comma-delimited list of app guids to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by responses: '200': description: List of packages content: application/json: schema: $ref: '#/components/schemas/PackageList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org?types=bits%2Cdocker&page=1&per_page=2 last: href: https://api.example.org?types=bits%2Cdocker&page=1&per_page=2 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 type: bits data: checksum: type: sha256 value: null error: null state: AWAITING_UPLOAD created_at: '2015-11-03T00:53:54Z' updated_at: '2016-06-08T16:41:26Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4 upload: href: https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/upload method: POST download: href: https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/download method: GET app: href: https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745 metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 type: docker data: image: registry/image:latest username: username password: '***' state: READY created_at: '2015-11-03T00:53:54Z' updated_at: '2016-06-08T16:41:26Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/packages/8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691 app: href: https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745 metadata: labels: {} annotations: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a package description: Create a package. operationId: createPackage tags: - Packages requestBody: $ref: '#/components/requestBodies/PackageCreateRequestBody' responses: '201': description: Successfully created package content: application/json: schema: $ref: '#/components/schemas/Package' examples: docker_app: summary: Docker app value: guid: 123e4567-e89b-12d3-a456-426614174000 type: docker data: image: registry/image:latest username: username password: '***' state: READY created_at: '2015-11-03T00:53:54Z' updated_at: '2016-06-08T16:41:26Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/packages/4cb65058-f04f-458f-aca1-5f4e43de6407 app: href: https://api.example.org/v3/apps/d8b8148d-5798-44de-821a-64b85b15e968 metadata: labels: {} annotations: {} links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this package '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/packages/{guid}: get: summary: Get a package description: Retrieve a package. operationId: getPackage tags: - Packages parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: Successfully retrieved package content: application/json: schema: $ref: '#/components/schemas/Package' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this package '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' patch: summary: Update a package description: Update a package. operationId: updatePackage tags: - Packages parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Package object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' username: type: string description: The username for the image’s registry. Only possible for Docker package. password: type: string description: The password for the image’s registry. Only possible for Docker package. examples: default: summary: default value: metadata: labels: key: value annotations: note: detailed information responses: '200': description: Successfully updated package content: application/json: schema: $ref: '#/components/schemas/Package' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a package description: Delete a package. operationId: deletePackage tags: - Packages parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the package schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/packages/{guid}/droplets: get: summary: List droplets for a package description: Retrieve a list of droplets belonging to a package. operationId: listPackageDroplets tags: - Packages - Droplets parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of droplet guids to filter by - name: states in: query schema: type: array items: type: string description: Comma-delimited list of droplet states to filter by responses: '200': description: List of droplets for the package content: application/json: schema: $ref: '#/components/schemas/DropletList' examples: default: summary: default value: pagination: total_results: 2 total_pages: 1 first: href: https://api.example.org?page=1&per_page=50 last: href: https://api.example.org?page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 state: STAGED error: null lifecycle: type: buildpack data: {} image: null execution_metadata: PRIVATE DATA HIDDEN process_types: redacted_message: 123e4567-e89b-12d3-a456-426614174000 checksum: type: sha256 value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 buildpacks: - name: ruby_buildpack detect_output: ruby 1.6.14 version: 1.1.1. buildpack_name: ruby stack: cflinuxfs4 created_at: '2016-03-28T23:39:34Z' updated_at: '2016-03-28T23:39:47Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 package: href: https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH download: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download metadata: labels: {} annotations: {} - guid: 123e4567-e89b-12d3-a456-426614174000 state: STAGED error: null lifecycle: type: docker data: {} execution_metadata: 123e4567-e89b-12d3-a456-426614174000 process_types: redacted_message: 123e4567-e89b-12d3-a456-426614174000 image: cloudfoundry/diego-docker-app-custom:latest checksum: null buildpacks: null stack: null created_at: '2016-03-17T00:00:01Z' updated_at: '2016-03-17T21:41:32Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22 package: href: https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 assign_current_droplet: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet method: PATCH metadata: labels: {} annotations: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/packages: get: summary: List packages for an app description: Retrieve packages for an app that the user has access to. operationId: listAppPackages tags: - Packages parameters: - $ref: '#/components/parameters/Guid' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of app GUIDs to filter by - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: states in: query schema: type: array items: type: string enum: - AWAITING_UPLOAD - PROCESSING_UPLOAD - READY - FAILED - COPYING - EXPIRED description: Comma-delimited list of package states to filter by - name: types in: query schema: type: array items: type: string enum: - bits - docker description: Comma-delimited list of package types to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PackageList' examples: default: summary: default value: pagination: total_results: 1 total_pages: 1 first: href: https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50 last: href: https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 type: bits data: error: null checksum: type: sha256 value: null state: READY created_at: '2016-03-17T21:41:09Z' updated_at: '2016-06-08T16:41:26Z' relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561 upload: href: https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/upload method: POST download: href: https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/download method: GET app: href: https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69 metadata: labels: {} annotations: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/packages/{guid}/upload: post: summary: Upload package bits description: This upload endpoint takes a multi-part form requests for packages of type `bits`. The request requires either a [.zip file](https://en.wikipedia.org/wiki/Zip_(file_format)) uploaded under the `bits` field or a list of [resource match objects](#the-resource-match-object) under the `resources` field. These field may be used together. operationId: uploadPackageBits tags: - Packages parameters: - $ref: '#/components/parameters/Guid' requestBody: content: multipart/form-data: schema: type: object properties: bits: type: string format: binary resources: type: array items: type: object properties: path: type: string size_in_bytes: type: integer checksum: type: object properties: value: type: string application/json: schema: type: object properties: resources: type: array items: type: object properties: path: type: string size_in_bytes: type: integer checksum: type: object properties: value: type: string responses: '200': description: Successfully uploaded package bits content: application/json: schema: $ref: '#/components/schemas/Package' '202': description: Upload initiated headers: Location: schema: type: string description: URL of the job tracking the upload content: application/json: schema: $ref: '#/components/schemas/Package' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/packages/{guid}/download: get: summary: Download package bits description: |- 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. operationId: downloadPackageBits tags: - Packages parameters: - $ref: '#/components/parameters/Guid' responses: '302': description: Redirect to download location '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/processes: get: summary: List processes description: Retrieve all processes. operationId: listProcesses tags: - Processes parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of process guids to filter by - name: types in: query schema: type: array items: type: string description: Comma-delimited list of process types to filter by - name: app_guids in: query schema: type: array items: type: string description: Comma-delimited list of app guids to filter by - name: space_guids in: query schema: type: array items: type: string description: Comma-delimited list of space guids to filter by - name: organization_guids in: query schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ProcessList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/processes/{guid}: get: summary: Get a process description: Get a process. operationId: getProcess tags: - Processes parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Process' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 type: web command: rackup user: vcap instances: 5 memory_in_mb: 256 disk_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 health_check: type: port data: timeout: null readiness_health_check: type: process data: invocation_timeout: null process_instances: - index: 0 state: RUNNING since: 123456789 - index: 1 state: STARTING since: 123 - index: 2 state: DOWN since: 456 relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 revision: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} created_at: '2016-03-23T18:48:22Z' updated_at: '2016-03-23T18:48:42Z' version: e9df685c-0464-4aa7-b5f0-8ed843077c13 links: self: href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 scale: href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale method: POST app: href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 stats: href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats process_instances: href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this process revision: operationId: getRevision parameters: guid: $response.body#/relationships/revision/data/guid description: Retrieve the revision for this process '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a process description: Update a process. operationId: updateProcess tags: - Processes parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/ProcessUpdateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Process' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this process revision: operationId: getRevision parameters: guid: $response.body#/relationships/revision/data/guid description: Retrieve the revision for this process '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/processes/{guid}/process_instances: get: summary: List instances for a process description: Retrieve the instances for a process. Unlike the stats endpoint, this returns a simplified view with only the index, state, and uptime of each instance. operationId: listProcessInstances tags: - Processes parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object properties: resources: type: array items: type: object properties: index: type: integer state: type: string enum: - RUNNING - CRASHED - STARTING - DOWN since: type: number format: double links: type: object properties: self: $ref: '#/components/schemas/Link' process: $ref: '#/components/schemas/Link' examples: default: summary: default value: resources: - index: 0 state: RUNNING since: 123456789 - index: 1 state: STARTING since: 123 - index: 2 state: DOWN since: 456 links: self: href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances process: href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/processes/{guid}/stats: get: summary: Get stats for a process description: Get stats for a process. operationId: getProcessStats tags: - Processes parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ProcessStats' examples: default: summary: default value: resources: - type: web index: 0 instance_guid: 123e4567-e89b-12d3-a456-426614174000 state: RUNNING routable: true usage: time: '2016-03-23T23:17:30.476314154Z' cpu: 0.00038711029163348665 cpu_entitlement: 0.01117396940977856 mem: 19177472 disk: 69705728 log_rate: 0 host: 10.244.16.10 instance_internal_ip: 10.255.93.167 instance_ports: - external: 64546 internal: 8080 external_tls_proxy_port: 61002 internal_tls_proxy_port: 61003 uptime: 9042 mem_quota: 268435456 disk_quota: 1073741824 fds_quota: 16384 isolation_segment: example_iso_segment log_rate_limit: null details: null - type: web index: 1 state: STARTING routable: false usage: cpu: 0 cpu_entitlement: 0 disk: 0 log_rate: 0 mem: 0 time: '2016-03-23T21:34:04+00:00' disk_quota: null fds_quota: 16384 host: '' instance_internal_ip: '' instance_ports: null isolation_segment: null log_rate_limit: null mem_quota: null uptime: 0 details: null '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/processes/{guid}/actions/scale: post: summary: Scale a process description: Scale a process. operationId: scaleProcess tags: - Processes parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: properties: instances: type: - integer - 'null' description: The number of instances to run memory_in_mb: type: - integer - 'null' description: The memory in MB allocated per instance disk_in_mb: type: - integer - 'null' description: The disk in MB allocated per instance log_rate_limit_in_bytes_per_second: type: - integer - 'null' description: The log rate limit in bytes per second per instance examples: default: summary: default value: instances: 5 memory_in_mb: 256 disk_in_mb: 1024 log_rate_limit_in_bytes_per_second: 1024 responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/Process' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/processes/{guid}/instances/{index}: delete: summary: Terminate a process instance description: |- 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. operationId: terminateProcessInstance tags: - Processes parameters: - $ref: '#/components/parameters/Guid' - name: index in: path required: true schema: type: integer responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/apps/{guid}/processes: get: summary: List processes for an app description: Retrieves all processes belonging to an app. operationId: listAppProcesses tags: - Processes parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ProcessList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/processes/{type}: get: summary: Get a process for an app description: Get a specific process for an app. operationId: getProcessForApp tags: - Processes parameters: - $ref: '#/components/parameters/Guid' - name: type in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Process' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a process for an app description: Update a specific process for an app. operationId: updateProcessForApp tags: - Processes parameters: - $ref: '#/components/parameters/Guid' - name: type in: path required: true schema: type: string requestBody: $ref: '#/components/requestBodies/ProcessUpdateRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Process' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/processes/{type}/stats: get: summary: Get stats for a process for an app description: Get stats for a specific process for an app. operationId: getProcessStatsForApp tags: - Processes parameters: - $ref: '#/components/parameters/Guid' - name: type in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ProcessStats' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/apps/{guid}/processes/{type}/actions/scale: post: summary: Scale a process for an app description: Scale a specific process for an app. operationId: scaleProcessForApp tags: - Processes parameters: - $ref: '#/components/parameters/Guid' - name: type in: path required: true schema: type: string requestBody: content: application/json: schema: properties: instances: type: - integer - 'null' description: The number of instances to run memory_in_mb: type: - integer - 'null' description: The memory in MB allocated per instance disk_in_mb: type: - integer - 'null' description: The disk in MB allocated per instance log_rate_limit_in_bytes_per_second: type: - integer - 'null' description: The log rate limit in bytes per second per instance responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/Process' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/processes/{type}/instances/{index}: delete: summary: Terminate a process instance for an app description: Terminate a specific process instance for an app. operationId: terminateProcessInstanceForApp tags: - Processes parameters: - $ref: '#/components/parameters/Guid' - name: type in: path required: true schema: type: string - name: index in: path required: true schema: type: integer responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/manifest: get: summary: Generate a manifest for an app description: Generate a manifest for an app and its underlying processes. operationId: generateManifest tags: - Manifests parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/x-yaml: schema: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/apps/{guid}/builds: get: summary: List builds for an app description: Retrieve all builds for an app. operationId: listAppBuilds tags: - Builds parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: states in: query schema: type: array items: type: string enum: - STAGING - STAGED - FAILED description: Comma-delimited list of build states to filter by - $ref: '#/components/parameters/LabelSelector' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/BuildList' examples: default: summary: default value: pagination: total_results: 1 total_pages: 1 first: href: https://api.example.org?states=STAGING&page=1&per_page=2 last: href: https://api.example.org?states=STAGING&page=1&per_page=2 next: null previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2016-03-28T23:39:34Z' updated_at: '2016-06-08T16:41:26Z' created_by: guid: 123e4567-e89b-12d3-a456-426614174000 name: bill email: bill@example.com state: STAGING staging_memory_in_mb: 1024 staging_disk_in_mb: 1024 staging_log_rate_limit_bytes_per_second: 1024 error: null lifecycle: type: buildpack data: buildpacks: - ruby_buildpack stack: cflinuxfs4 package: guid: 123e4567-e89b-12d3-a456-426614174000 droplet: null relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 metadata: labels: {} annotations: {} links: self: href: https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16 app: href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a build description: Update a build. operationId: updateBuildViaApp tags: - Builds parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Build object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a build responses: '200': description: Successfully updated build content: application/json: schema: $ref: '#/components/schemas/Build' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/tasks: get: summary: List tasks for an app description: Retrieve tasks for an app. operationId: listAppTasks tags: - Tasks parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query schema: type: array items: type: string description: Comma-delimited list of task guids to filter by - name: names in: query schema: type: array items: type: string description: Comma-delimited list of task names to filter by - name: states in: query schema: type: array items: type: string enum: - PENDING - RUNNING - SUCCEEDED - CANCELING - FAILED description: Comma-delimited list of task states to filter by - name: sequence_ids in: query schema: type: array items: type: integer description: Comma-delimited list of sequence ids to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TaskList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: summary: Create a task description: Create a task. operationId: createTask tags: - Tasks parameters: - $ref: '#/components/parameters/Guid' requestBody: $ref: '#/components/requestBodies/TaskCreateRequestBody' responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/Task' links: app: operationId: getApp parameters: guid: $response.body#/relationships/app/data/guid description: Retrieve the app for this task droplet: operationId: getDroplet parameters: guid: $response.body#/droplet_guid description: Retrieve the droplet for this task '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/apps/{guid}/actions/clear_buildpack_cache: post: summary: Clear buildpack cache for application description: 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. operationId: clearBuildpackCacheForApplication tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/env: get: summary: Get environment for an app description: 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. operationId: getEnvForApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppEnvironment' examples: default: summary: default value: staging_env_json: GEM_CACHE: http://gem-cache.example.org running_env_json: HTTP_PROXY: http://proxy.example.org environment_variables: RAILS_ENV: production system_env_json: VCAP_SERVICES: mysql: - name: db-for-my-app binding_id: 0e85b634-e043-4b43-96da-f83dfe83ab33 binding_name: db-for-my-app instance_id: 07fca01c-f789-4d45-80b4-e19ba3ca862c instance_name: my-mysql-service label: mysql tags: - relational - sql plan: xlarge credentials: username: user password: top-secret syslog_drain_url: https://syslog.example.org/drain volume_mounts: [] provider: null application_env_json: VCAP_APPLICATION: limits: fds: 16384 application_name: my_app application_uris: - my_app.example.org name: my_app space_name: my_space space_id: 2f35885d-0c9d-4423-83ad-fd05066f8576 uris: - my_app.example.org users: null '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/environment_variables: get: summary: Get environment variables for an app description: 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. operationId: getEnvironmentVariablesForApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppEnvironmentVariables' examples: default: summary: default value: var: RAILS_ENV: production links: self: href: https://api.example.org/v3/apps/[guid]/environment_variables app: href: https://api.example.org/v3/apps/[guid] '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update environment variables for an app description: 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. operationId: updateEnvironmentVariablesForApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: type: object properties: var: type: object additionalProperties: type: - string - 'null' description: Environment variables to inject; keys and values must be strings examples: default: summary: default value: var: DEBUG: 'false' USER: null responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppEnvironmentVariables' examples: default: summary: default value: var: RAILS_ENV: production DEBUG: 'false' links: self: href: https://api.example.org/v3/apps/[guid]/environment_variables app: href: https://api.example.org/v3/apps/[guid] '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/features: get: summary: List app features description: This endpoint retrieves the list of features for the specified app. operationId: listAppFeatures tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/features/{name}: get: summary: Get an app feature description: Get an app feature. operationId: getAppFeature tags: - Apps parameters: - $ref: '#/components/parameters/Guid' - name: name in: path required: true schema: type: string enum: - ssh - revisions - service-binding-k8s - file-based-vcap-services responses: '200': description: OK '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update an app feature description: Update an app feature. operationId: updateAppFeature tags: - Apps parameters: - $ref: '#/components/parameters/Guid' - name: name in: path required: true schema: type: string enum: - ssh - revisions - service-binding-k8s - file-based-vcap-services requestBody: content: application/json: schema: properties: enabled: type: boolean examples: default: summary: default value: enabled: false responses: '200': description: OK '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/apps/{guid}/permissions: get: summary: Get permissions for an app description: 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. operationId: getPermissionsForApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppPermissions' examples: default: summary: default value: read_basic_data: true read_sensitive_data: false '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/routes: get: summary: List routes for an app description: Retrieve all routes that have destinations that point to the given app. operationId: listAppRoutes tags: - Routes parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: domain_guids in: query schema: type: array items: type: string description: Comma-delimited list of domain guids to filter by - name: hosts in: query schema: type: array items: type: string description: Comma-delimited list of hostnames to filter by - name: paths in: query schema: type: array items: type: string description: Comma-delimited list of paths to filter by - name: ports in: query schema: type: array items: type: integer description: Comma-delimited list of ports to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RouteList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org<%= path %>?page=1&per_page=2 last: href: https://api.example.org<%= path %>?page=2&per_page=2 next: href: https://api.example.org<%= path %>?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 protocol: http created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' host: a-hostname path: /some_path url: a-hostname.a-domain.com/some_path destinations: - guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: web weight: null port: 8080 protocol: http1 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' - guid: 123e4567-e89b-12d3-a456-426614174000 app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: web weight: null port: 8080 protocol: http1 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' options: loadbalancing: round-robin metadata: labels: {} annotations: {} relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 domain: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 space: href: https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236 domain: href: https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e destinations: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/apps/{guid}/ssh_enabled: get: summary: Get SSH enabled for an app description: 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. operationId: getSshEnabledForApp tags: - Apps parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppSshEnabled' examples: default: summary: default value: enabled: false reason: Disabled globally '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/domains/{guid}/route_reservations: get: summary: Check reserved routes for a domain description: 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. operationId: checkReservedRoutesForDomain tags: - Domains parameters: - $ref: '#/components/parameters/Guid' - name: host in: query schema: type: string description: Hostname to filter by - name: path in: query schema: type: string description: Path to filter by - name: port in: query schema: type: integer description: Port to filter by responses: '200': description: OK content: application/json: schema: type: object properties: matching_route: type: boolean examples: default: summary: default value: matching_route: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/organizations/{guid}/domains: get: summary: List domains for an organization description: |- 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](#get-default-domain) endpoint. operationId: listDomainsForOrganization tags: - Domains parameters: - $ref: '#/components/parameters/Guid' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - name: names in: query schema: type: array items: type: string description: Comma-delimited list of domain names to filter by responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DomainList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2019-03-08T01:06:19Z' updated_at: '2019-03-08T01:06:19Z' name: test-domain.com internal: false router_group: guid: 123e4567-e89b-12d3-a456-426614174000 supported_protocols: - tcp metadata: labels: {} annotations: {} relationships: organization: data: null shared_organizations: data: [] links: self: href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 route_reservations: href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations router_group: href: https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/processes/{guid}/sidecars: get: summary: List sidecars for process description: Retrieves all sidecars associated with a process. operationId: listProcessSidecars tags: - Sidecars parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SidecarList' examples: default: summary: default value: pagination: total_results: 3 total_pages: 2 first: href: https://api.example.org?page=1&per_page=2 last: href: https://api.example.org?page=2&per_page=2 next: href: https://api.example.org?page=2&per_page=2 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 name: auth-sidecar command: bundle exec rackup process_types: - web - worker memory_in_mb: 300 origin: user relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' - guid: 123e4567-e89b-12d3-a456-426614174000 name: echo-sidecar command: start-echo-server process_types: - web memory_in_mb: 300 origin: user relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2017-02-01T01:33:59Z' updated_at: '2017-02-01T01:33:59Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/routes/{guid}: get: summary: Get a route description: Retrieve a route. operationId: getRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' - name: include in: query schema: type: array items: type: string enum: - domain - space - space.organization description: Optionally include a list of unique related resources in the response responses: '200': description: Successfully retrieved route content: application/json: schema: $ref: '#/components/schemas/Route' links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this route domain: operationId: getDomain parameters: guid: $response.body#/relationships/domain/data/guid description: Retrieve the domain for this route '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a route description: Update a route. operationId: updateRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' requestBody: description: Route object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a route responses: '200': description: Successfully updated route content: application/json: schema: $ref: '#/components/schemas/Route' links: space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this route domain: operationId: getDomain parameters: guid: $response.body#/relationships/domain/data/guid description: Retrieve the domain for this route '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' delete: summary: Delete a route description: Delete a route. operationId: deleteRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Successfully deleted route headers: Location: description: URL of the job that is deleting the route schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' /v3/routes/{guid}/relationships/shared_spaces: get: summary: List shared spaces relationship description: Lists the spaces that the route has been shared to. operationId: listSharedSpacesRelationship tags: - Routes parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: summary: Share a route with other spaces (experimental) description: 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. operationId: shareRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' requestBody: description: List of spaces to share the route with required: true content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/routes/{guid}/relationships/shared_spaces/{space_guid}: delete: summary: Unshare a route that was shared with another space (experimental) description: Unshares a route that was shared with another space. operationId: unshareRoute tags: - Routes parameters: - $ref: '#/components/parameters/Guid' - name: space_guid in: path required: true schema: type: string format: uuid description: The GUID of the space to unshare the route from responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/routes/{guid}/relationships/space: patch: summary: Transfer ownership (experimental) description: 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](#share-a-route-with-other-spaces-experimental). To completely remove a space from a route, users will have to use [unshare route](#unshare-a-route-that-was-shared-with-another-space-experimental). operationId: transferRouteOwnership tags: - Routes parameters: - $ref: '#/components/parameters/Guid' requestBody: description: The space to transfer ownership to required: true content: application/json: schema: $ref: '#/components/schemas/RelationshipToOne' responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/service_instances/{guid}/credentials: get: summary: Get credentials for a user-provided service instance description: Retrieves the credentials for a user-provided service instance. This endpoint is not available for managed service instances. operationId: getServiceInstanceCredentials tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object examples: default: summary: default value: username: my-username password: super-secret other: credential '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/service_instances/{guid}/parameters: get: summary: Get parameters for a managed service instance description: 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](#the-service-offering-object) for the value of this feature flag. operationId: getServiceInstanceParameters tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object examples: default: summary: default value: key_1: value_1 key_2: value_2 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/service_instances/{guid}/permissions: get: summary: Get permissions for a service instance description: |- 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](https://docs.cloudfoundry.org/services/dashboard-sso.html). operationId: getServiceInstancePermissions tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object properties: read: type: boolean manage: type: boolean examples: default: summary: default value: read: true manage: false '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/service_instances/{guid}/relationships/shared_spaces: get: summary: List shared spaces relationship description: This endpoint lists the spaces that the service instance has been shared to. operationId: listServiceInstanceSharedSpaces tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' - name: fields in: query schema: type: object description: Fields to include in the response responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: summary: Share a service instance to other spaces description: 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. operationId: shareServiceInstance tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RelationshipToMany' examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - guid: 123e4567-e89b-12d3-a456-426614174000 links: self: href: https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v3/service_instances/{guid}/relationships/shared_spaces/usage_summary: get: summary: Get usage summary in shared spaces description: This endpoint returns the number of bound apps in spaces where the service instance has been shared to. operationId: getServiceInstanceUsageSummaryInSharedSpaces tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' responses: '200': description: OK content: application/json: schema: type: object properties: usage_summary: type: array items: type: object properties: space: $ref: '#/components/schemas/Relationship' bound_app_count: type: integer examples: default: summary: default value: usage_summary: - space: guid: 123e4567-e89b-12d3-a456-426614174000 bound_app_count: 2 - space: guid: 123e4567-e89b-12d3-a456-426614174000 bound_app_count: 0 links: self: href: https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces/usage_summary shared_spaces: href: https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces service_instance: href: https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /v3/service_instances/{guid}/relationships/shared_spaces/{space_guid}: delete: summary: Unshare a service instance from another space description: 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. operationId: unshareServiceInstance tags: - Service Instances parameters: - $ref: '#/components/parameters/Guid' - name: space_guid in: path required: true schema: type: string format: uuid responses: '204': description: No Content '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' components: schemas: BaseSchema: type: object properties: guid: type: string format: uuid description: The unique identifier for the resource created_at: type: string format: date-time description: The ISO8601 compatible date and time when resource was created updated_at: type: string format: date-time description: The ISO8601 compatible date and time when resource was last updated description: | A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object. A resource consists of several required resource fields and other attributes specific to the resource. See Resources and Experimental Resources for specific resources. Relationships: type: object description: | 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. Relationship: type: object properties: guid: type: string format: uuid description: The GUID of the resource RelationshipToOne: type: object properties: data: type: - object - 'null' $ref: '#/components/schemas/Relationship' links: type: object properties: self: $ref: '#/components/schemas/Link' related: $ref: '#/components/schemas/Link' description: | Some relationships relate a resource to exactly one other resource. For example an app can belong to only one space. RelationshipToMany: type: object properties: data: type: array items: $ref: '#/components/schemas/Relationship' links: type: object properties: self: $ref: '#/components/schemas/Link' related: $ref: '#/components/schemas/Link' description: | Some relationships relate a resource to several other resources. For example, an isolation segment can be entitled to multiple organizations. UserRelationshipToOne: type: - object - 'null' properties: data: type: object description: | User relationship data that can be specified either by GUID or by username and origin. When using username and origin, the set_roles_by_username feature flag must be enabled. oneOf: - type: object properties: guid: type: string description: The GUID of the user, matching either a UAA user id or client id. A client id may not be a uuid. required: - guid additionalProperties: false - type: object properties: username: type: string description: The username of the user origin: type: string description: The identity provider for the user (e.g., 'ldap', 'saml'). Optional field to disambiguate the username. required: - username additionalProperties: false description: | User relationship data that can be specified either by GUID or by username and origin. Set to null to clear the relationship. IncludedResources: type: object description: Additional related resources included in the response when using the include parameter properties: spaces: type: array items: $ref: '#/components/schemas/Space' description: Array of included space resources organizations: type: array items: $ref: '#/components/schemas/Organization' description: Array of included organization resources domains: type: array items: $ref: '#/components/schemas/Domain' description: Array of included domain resources service_offerings: type: array items: $ref: '#/components/schemas/ServiceOffering' description: Array of included service offering resources service_instances: type: array items: oneOf: - $ref: '#/components/schemas/ManagedServiceInstance' - $ref: '#/components/schemas/UserProvidedServiceInstance' discriminator: propertyName: type mapping: managed: '#/components/schemas/ManagedServiceInstance' user-provided: '#/components/schemas/UserProvidedServiceInstance' description: Array of included service instance resources apps: type: array items: $ref: '#/components/schemas/App' description: Array of included app resources routes: type: array items: $ref: '#/components/schemas/Route' description: Array of included route resources users: type: array items: $ref: '#/components/schemas/User' description: Array of included user resources additionalProperties: false Link: type: object properties: href: type: string description: The URL of the link method: type: string description: An optional field containing the HTTP method to be used when following the URL required: - href description: | Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET. Pagination: type: object properties: total_results: type: integer description: The total number of results available total_pages: type: integer description: The total number of pages available first: allOf: - $ref: '#/components/schemas/Link' - description: The first page of results last: allOf: - $ref: '#/components/schemas/Link' - description: The last page of results next: oneOf: - $ref: '#/components/schemas/Link' - type: 'null' description: The next page of results previous: oneOf: - $ref: '#/components/schemas/Link' - type: 'null' description: The previous page of results description: | Pagination is a technique used to divide a large set of results into smaller, more manageable sets. This allows clients to retrieve results in smaller chunks, reducing the amount of data transferred and improving performance. The pagination object is a JSON object that contains information about the pagination state of the results. It includes the total number of results available, the total number of pages available, and links to the first, last, next, and previous pages of results. Metadata: type: object properties: labels: type: object additionalProperties: type: - string - 'null' description: | A set of key-value pairs that describe the resource. Labels are a JSON object that contains information about a resource. They are used to tag resources with metadata that can be used to filter and group resources. Labels are included in the response body of a request to retrieve a resource. Labels are user-specified key/value pairs that are attached to API Resources. They are queryable, identifying attributes of a resource, but they do not affect the operation of CloudFoundry. For example, an app may be assigned a label with key sensitive and possible values true or false. Users could then find all sensitive apps with a selector for sensitive=true, resulting in a response containing only apps having the label key sensitive with a label value of true. Labels Labels allow users to apply identifying attributes to resources that are meaningful to the user, but not the CloudFoundry system. Examples may include (but are not limited to): "production" : "true" or "production" : "false" "env" : "dev" or "env" : "test" or "env" : "prod" "chargeback-code" : "abc123" Label keys Label keys are made up of an (optional) prefix, and name. If a prefix is present, it is separated from the name by a /. Prefixes are dns names intended to enable namespacing of label keys. A label key prefix must adhere to the following restrictions: Length: 0-253 characters Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, and . DNS subdomain format (series of subdomain labels separated by .) A label key name must adhere to the following restrictions: Length: 1-63 characters Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, _, and . Must begin and end with an alphanumeric character Label values Label values must adhere to the following restrictions: Length: 0-63 characters Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, _, and . Must begin and end with an alphanumeric character Empty values are allowed annotations: type: object additionalProperties: type: - string - 'null' description: | A set of key-value pairs that describe the resource. Annotations are a JSON object that contains information about a resource. They are used to tag resources with metadata that can be used to filter and group resources. Annotations are included in the response body of a request to retrieve a resource. Annotations are user-specified key-value pairs that are attached to API resources. They do not affect the operation of Cloud Foundry. Annotations cannot be used in filters. When a service instance is being created, the service broker is sent the annotations of the service instance, and the space and organization in which the service instance resides. When a service instance is being updated, the service broker is sent the annotations of the space and organization in which the service instance resides. When a service binding is being created, the service broker is sent annotations of any associated app, and the space and organization in which the binding resides. Only annotations with a prefix (e.g. company.com/contacts) are sent to service brokers. Examples may include (but are not limited to): "contact info": "bob@example.com jane@example.com" "library versions": "Spring: 5.1, Redis Client: a184098. yaml parser: 38" "git-sha": "d56fe0367554ae5e878e37ed6c5b9a82f5995512" Annotation keys Annotation keys are made up of an (optional) prefix and name. If a prefix is present, it is separated from the name by a /. Prefixes are DNS names intended to enable namespacing of annotation keys. An annotation key prefix must adhere to the following restrictions: Length: 0-253 characters Allowed characters: a-z, A-Z, 0-9, -, and .; emojis cannot be used in keys DNS subdomain format (series of subdomain annotations separated by .) An annotation key name must adhere to the following restrictions: Length: 1-63 characters Allowed characters: a-z, A-Z, 0-9, -, _, and .; emojis cannot be used in keys Must begin and end with an alphanumeric character Annotation values Annotation values must adhere to the following restrictions: Length: 0-5000 unicode characters description: | 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. Buildpack: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: The name of the buildpack; to be used by app buildpack field (only alphanumeric characters) state: type: string description: The state of the buildpack enum: - AWAITING_UPLOAD - READY stack: type: - string - 'null' description: The name of the stack that the buildpack uses lifecycle: type: string description: The version of buildpacks the buildpack uses. `buildpack` indicates [Classic Buildpacks](https://docs.cloudfoundry.org/buildpacks/classic.html). `cnb` indicates [Cloud Native Buildpacks](https://docs.cloudfoundry.org/buildpacks/cnb/) position: type: integer description: The order in which the buildpacks are checked during buildpack auto-detection enabled: type: boolean description: Whether or not the buildpack can be used for staging locked: type: boolean description: Whether or not the buildpack is locked to prevent updating the bits filename: type: - string - 'null' description: The filename of the buildpack metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL of the buildpack upload: $ref: '#/components/schemas/Link' description: The URL to upload the buildpack description: A buildpack represents a set of scripts used to prepare an application for launch. BuildpackList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Buildpack' User: type: object properties: guid: type: string description: Unique identifier for the user, matching either a UAA user id or client id. A client id may not be a uuid. created_at: type: string format: date-time description: The ISO8601 compatible date and time when resource was created updated_at: type: string format: date-time description: The ISO8601 compatible date and time when resource was last updated username: type: - string - 'null' description: The username of the user presentation_name: type: string description: The presentation name of the user origin: type: - string - 'null' description: The origin of the user metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this user Droplet: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: state: type: string description: State of the droplet; valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, STAGED, COPYING, FAILED, or EXPIRED error: type: - string - 'null' description: A string describing the last error during the droplet lifecycle lifecycle: $ref: '#/components/schemas/Lifecycle' execution_metadata: type: - string - 'null' description: Serialized JSON data resulting from staging for use when executing a droplet process_types: type: object description: The process types (keys) and associated start commands (values) that will be created when the droplet is executed metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this droplet package: $ref: '#/components/schemas/Link' description: The URL to get the package for this droplet app: $ref: '#/components/schemas/Link' description: The URL to get the app for this droplet assign_current_droplet: $ref: '#/components/schemas/Link' description: The URL to assign the droplet to an application download: $ref: '#/components/schemas/Link' description: The URL to download the droplet upload: $ref: '#/components/schemas/Link' description: The URL to upload the droplet checksum: type: - object - 'null' properties: type: type: string description: Hashing algorithm for checksum; supported algorithms are sha256 and sha1 value: type: string description: Checksum of the droplet buildpacks: type: - array - 'null' items: type: object properties: name: type: - string - 'null' description: System buildpack name detect_output: type: - string - 'null' description: Output during buildpack detect process version: type: - string - 'null' description: Version reported by the buildpack buildpack_name: type: - string - 'null' description: Name reported by the buildpack stack: type: - string - 'null' description: The root filesystem to use with the buildpack, for example cflinuxfs4 image: type: - string - 'null' description: Docker image name for Docker droplets description: A droplet is the result of staging an application package. There are two types (lifecycles) of droplets buildpack and docker. In the case of the buildpacks, the droplet contains the bits produced by the buildpack, typically application code and dependencies. DropletList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Droplet' Lifecycle: type: object properties: type: type: string description: Type of the lifecycle; valid values are buildpack, cnb, docker data: type: object additionalProperties: true description: Data specific to the lifecycle properties: buildpacks: type: array items: type: string description: List of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack during staging (applicable for buildpack and cnb lifecycles) stack: type: - string - 'null' description: The root filesystem to use with the buildpack, for example cflinuxfs4 (applicable for buildpack lifecycle) credentials: type: object additionalProperties: type: object properties: username: type: - string - 'null' password: type: - string - 'null' token: type: string description: Credentials used to download the configured buildpacks (applicable for cnb lifecycle) description: | 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. Domain: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: The name of the domain; must be between 3 ~ 253 characters and follow [RFC 1035](https://tools.ietf.org/html/rfc1035) internal: type: boolean description: Whether the domain is used for internal (container-to-container) traffic router_group: type: - object - 'null' properties: guid: type: string format: uuid description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic supported_protocols: type: array items: type: string enum: - http - tcp description: Available protocols for routes using the domain, currently `http` and `tcp` relationships: $ref: '#/components/schemas/Relationships' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this domain organization: $ref: '#/components/schemas/Link' description: The URL to get the organization for this domain route_reservations: $ref: '#/components/schemas/Link' description: The URL to get the route reservations for this domain shared_organizations: $ref: '#/components/schemas/Link' description: The URL to get the shared organizations for this domain router_group: $ref: '#/components/schemas/Link' description: The URL to get the router group for this domain description: | A domain is a fully qualified domain name that is used for application routes. A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access. DomainList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Domain' EnvironmentVariableGroup: type: object properties: updated_at: type: string format: date-time description: The time the environment variable group was last updated name: type: - string - 'null' description: The name of the group; can only be "running" or "staging" var: type: object additionalProperties: type: - string - 'null' description: Environment variables to inject; keys and values must be strings links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this environment variable group description: | Environment variable groups allow platform operators/admins to manage environment variables across all apps in a Cloud Foundry foundation. Variables in the running environment variable group will be injected into all running app containers. Variables in the staging environment variable group will be injected into the staging container for all apps while they are being staged. Deployment: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: status: type: object properties: value: type: string description: The current status of the deployment enum: - ACTIVE - FINALIZED reason: type: string description: The reason for the status of the deployment enum: - DEPLOYING - PAUSED - CANCELING - DEPLOYED - CANCELED - SUPERSEDED details: type: object properties: last_successful_healthcheck: type: string format: date-time description: Timestamp of the last successful health check last_status_change: type: string format: date-time description: Timestamp of last change to status.value or status.reason strategy: type: string description: Strategy used for the deployment enum: - rolling - canary options: type: object properties: max_in_flight: type: integer description: The maximum number of new instances to deploy simultaneously web_instances: type: integer description: The number of instances for the web process of the new droplet memory_in_mb: type: integer description: The amount of memory in megabytes to allocate for the web process disk_in_mb: type: integer description: The amount of disk space in megabytes to allocate for the web process log_rate_limit_in_bytes_per_second: type: integer description: The log rate limit in bytes per second for the web process. A value of -1 indicates unlimited, 0 prevents any logs from being emitted. canary: type: object description: Configuration for canary deployments. Present when strategy is 'canary'. properties: steps: type: array description: Array of steps defining the canary deployment progression items: type: object properties: instance_weight: type: integer description: The percentage of instances to be deployed as part of the canary process in this step droplet: type: object properties: guid: type: string format: uuid description: The droplet guid that the deployment is transitioning the app to previous_droplet: type: object properties: guid: type: string format: uuid description: The app’s [current droplet guid](#get-current-droplet-association-for-an-app) before the deployment was created new_processes: type: array items: type: object properties: guid: type: string format: uuid description: The GUID of the new process created as part of the deployment type: type: string description: The type of the new process created as part of the deployment revision: type: - object - 'null' properties: guid: type: string format: uuid description: The revision the deployment is transitioning the app to version: type: integer description: The version of the revision relationships: $ref: '#/components/schemas/Relationships' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this deployment app: $ref: '#/components/schemas/Link' description: The URL to get the app for this deployment cancel: $ref: '#/components/schemas/Link' description: The URL to cancel this deployment continue: $ref: '#/components/schemas/Link' description: The URL to continue this deployment description: | Deployments are objects that manage updates to applications with zero downtime. They can either: - Manage updating an app’s droplet directly after an application package is staged - Roll an app back to a specific revision along with its associated droplet Deployment strategies supported: - Rolling deployments allow for applications to be deployed without incurring downtime by gradually rolling out instances. Max-in-flight can be configured to specify how many instances are rolled out simultaneously. - Canary deployments deploy a single instance and pause for user evaluation. If the canary instance is deemed successful, the deployment can be resumed via the continue action. The deployment then continues like a rolling deployment. This feature is experimental and is subject to change. DeploymentList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Deployment' FeatureFlag: type: object properties: name: type: string description: The name of the feature flag enabled: type: boolean description: Whether the feature flag is enabled updated_at: type: - string - 'null' format: date-time description: The time the feature flag was last updated; this will be blank for feature flags that have not been configured custom_error_message: type: - string - 'null' description: The error string returned by the API when a client performs an action disabled by the feature flag links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this feature flag description: | Feature flags are runtime flags that enable or disable functionality on the API. FeatureFlagList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/FeatureFlag' Build: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: state: type: string description: State of the build enum: - STAGING - STAGED - FAILED staging_memory_in_mb: type: - integer - 'null' description: Memory in MB allocated for staging of the build staging_disk_in_mb: type: - integer - 'null' description: Disk space in MB allocated for staging of the build staging_log_rate_limit_bytes_per_second: type: integer description: Log rate limit in bytes per second allocated for staging of the build error: type: - string - 'null' description: A string describing errors during the build process lifecycle: $ref: '#/components/schemas/Lifecycle' description: Provides the lifecycle object to use during staging; this will override the build’s application’s default lifecycle for this build checksum: type: object properties: type: type: string description: Hashing algorithm for checksum; supported algorithms are sha256 and sha1 value: type: string description: Checksum of build metadata: $ref: '#/components/schemas/Metadata' relationships: $ref: '#/components/schemas/Relationships' package: type: object properties: guid: type: string format: uuid description: The package that is the input to the staging process droplet: type: - object - 'null' properties: guid: type: string format: uuid description: A resulting droplet from the staging process; `droplet` will be `null` if staging has not completed created_by: type: object properties: guid: type: string description: The guid of the user that created the build name: type: - string - 'null' description: The name of the user that created the build email: type: - string - 'null' description: The email of the user that created the build links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this build app: $ref: '#/components/schemas/Link' description: The URL to get the app for this build droplet: $ref: '#/components/schemas/Link' description: The URL to get the droplet for this build description: | Builds represent the process of transforming source code into a runnable artifact. Builds can be triggered manually or automatically as part of the app lifecycle. A successful build results in a droplet that can be used to run the app. BuildList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Build' AuditEvent: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: type: type: string description: The type of the event actor: type: object properties: guid: type: string description: The unique identifier for the actor (user or system resource that performed the action) type: type: string description: The actor type name: type: string description: The name of the actor target: type: object properties: guid: type: string description: The unique identifier for the target (resource that the event acted upon) type: type: string description: The target type name: type: string description: The name of the target data: type: object description: Additional information about event space: type: - object - 'null' properties: guid: type: string description: Unique identifier for the space where the event occurred; if the event did not occur within a space, the `space` field will be `null` organization: type: - object - 'null' properties: guid: type: string description: Unique identifier for the organization where the event occurred; if the event did not occur within an organization, the `organization` field will be `null` links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this audit event description: | Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions. AuditEventList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/AuditEvent' App: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: The name of the app state: type: string description: Current desired state of the app enum: - STOPPED - STARTED lifecycle: $ref: '#/components/schemas/Lifecycle' description: Provides the default lifecycle object for the application. This lifecycle will be used when staging and running the application. The staging lifecycle can be overridden on builds relationships: $ref: '#/components/schemas/Relationships' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this app space: $ref: '#/components/schemas/Link' description: The URL to get the space for this app processes: $ref: '#/components/schemas/Link' description: The URL to get the processes for this app packages: $ref: '#/components/schemas/Link' description: The URL to get the packages for this app environment_variables: $ref: '#/components/schemas/Link' description: The URL to get the environment variables for this app current_droplet: $ref: '#/components/schemas/Link' description: The URL to get the current droplet for this app droplets: $ref: '#/components/schemas/Link' description: The URL to get the droplets for this app tasks: $ref: '#/components/schemas/Link' description: The URL to get the tasks for this app start: $ref: '#/components/schemas/Link' description: The URL to start the app stop: $ref: '#/components/schemas/Link' description: The URL to stop the app revisions: $ref: '#/components/schemas/Link' description: The URL to get the revisions for this app deployed_revisions: $ref: '#/components/schemas/Link' description: The URL to get the deployed revisions for this app features: $ref: '#/components/schemas/Link' description: The URL to get the features for this app included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter description: | 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. AppList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/App' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter AppEnvironment: type: object properties: staging_env_json: type: object description: Environment variables used during staging additionalProperties: true running_env_json: type: object description: Environment variables used during runtime additionalProperties: true environment_variables: type: object description: User-defined environment variables additionalProperties: type: - string - 'null' system_env_json: type: object description: System environment variables including VCAP_SERVICES additionalProperties: true application_env_json: type: object description: Application environment variables including VCAP_APPLICATION additionalProperties: true description: Environment variables that will be provided to an app at runtime AppEnvironmentVariables: type: object properties: var: type: object description: Environment variables additionalProperties: type: - string - 'null' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get the environment variables for this app app: $ref: '#/components/schemas/Link' description: The URL to get the app for these environment variables description: App environment variables with links AppPermissions: type: object properties: read_basic_data: type: boolean description: Whether the user can read basic app data read_sensitive_data: type: boolean description: Whether the user can read sensitive app data required: - read_basic_data - read_sensitive_data description: User permissions for an app AppSshEnabled: type: object properties: enabled: type: boolean description: Whether SSH is enabled for the app reason: type: string description: If SSH is disabled, describes whether it is disabled globally, at the space level, or at the app level required: - enabled description: SSH enabled status for an app Route: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: protocol: type: string host: type: string path: type: string port: type: - integer - 'null' url: type: string description: Fully qualified path or address where the route directs traffic relationships: $ref: '#/components/schemas/Relationships' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this route space: $ref: '#/components/schemas/Link' description: The URL to get the space for this route domain: $ref: '#/components/schemas/Link' description: The URL to get the domain for this route destinations: $ref: '#/components/schemas/Link' description: The URL to get the destinations for this route included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter description: A route in Cloud Foundry is used to direct traffic from a URL to an application. RouteDestination: type: object properties: guid: type: string app: type: object properties: guid: type: string process: type: object properties: type: type: string weight: type: - integer - 'null' port: type: integer protocol: type: - string - 'null' created_at: type: string format: date-time updated_at: type: - string - 'null' format: date-time metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this route destination route: $ref: '#/components/schemas/Link' description: The URL to get the route for this destination description: A route destination is a specification for where traffic on a route should be directed. RouteDestinationList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' destinations: type: array items: $ref: '#/components/schemas/RouteDestination' description: A list of route destinations Job: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: operation: type: string description: The type of operation the job is performing state: type: string description: The current state of the job enum: - PROCESSING - COMPLETE - FAILED - POLLING errors: type: array description: Any errors encountered during job execution items: $ref: '#/components/schemas/Error' warnings: type: array description: Any warnings encountered during job execution items: $ref: '#/components/schemas/Warning' links: type: object additionalProperties: true properties: self: $ref: '#/components/schemas/Link' description: The URL to get this job manifest: $ref: '#/components/schemas/Link' description: The URL to get the manifest for this job service_brokers: $ref: '#/components/schemas/Link' description: The URL to get the service broker for this job service_credential_binding: $ref: '#/components/schemas/Link' description: The URL to get the service credential binding for this job service_instances: $ref: '#/components/schemas/Link' description: The URL to get the service instance for this job service_route_bindings: $ref: '#/components/schemas/Link' description: The URL to get the service route binding for this job description: Jobs are created by the platform when performing certain asynchronous actions. Asynchronous jobs are commonly used for long-running tasks such as uploading large files, staging applications, or deleting resources. Error: type: object properties: code: type: integer description: A numeric code for this error detail: type: string description: Detailed description of the error title: type: string description: Name of the error Warning: type: object properties: detail: type: string description: Description of the warning AppUsageEvent: type: object allOf: - $ref: '#/components/schemas/BaseSchema' properties: state: type: object properties: current: type: string description: Current state of the app that this event pertains to, if applicable previous: type: - string - 'null' description: Previous state of the app that this event pertains to, if applicable app: type: object properties: guid: type: string description: Unique identifier of the app that this event pertains to, if applicable name: type: - string - 'null' description: Name of the app that this event pertains to, if applicable process: type: object properties: guid: type: string description: Unique identifier of the process that this event pertains to, if applicable type: type: string description: Type of the process that this event pertains to, if applicable space: type: object properties: guid: type: string description: Unique identifier of the space that this event pertains to, if applicable name: type: - string - 'null' description: Name of the space that this event pertains to, if applicable organization: type: object properties: guid: type: string description: Unique identifier of the org that this event pertains to, if applicable buildpack: type: object properties: guid: type: string description: Unique identifier of the buildpack that this event pertains to, if applicable name: type: - string - 'null' description: Name of the buildpack that this event pertains to, if applicable task: type: object properties: guid: type: string description: Unique identifier of the task that this event pertains to, if applicable name: type: - string - 'null' description: Name of the task that this event pertains to, if applicable memory_in_mb_per_instance: type: object properties: current: type: integer description: Current memory in MB of the app that this event pertains to, if applicable previous: type: - integer - 'null' description: Previous memory in MB of the app that this event pertains to, if applicable instance_count: type: object properties: current: type: integer description: Current instance count of the app that this event pertains to, if applicable previous: type: - integer - 'null' description: Previous instance count of the app that this event pertains to, if applicable description: |- App usage events are a record of changes in the usage of apps and tasks. Examples include starting an application, scaling an application (from, say, one to three instances), and stopping an application. Usage events are typically used by billing and chargeback applications. AppUsageEventList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/AppUsageEvent' IsolationSegment: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: The name of the isolation segment metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this isolation segment organizations: $ref: '#/components/schemas/Link' description: The URL to get the organizations for this isolation segment description: An isolation segment provides a dedicated pool of compute resources for an organization or space. IsolationSegmentList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/IsolationSegment' Organization: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the organization suspended: type: boolean description: Whether an organization is suspended or not; non-admins will be blocked from creating, updating, or deleting resources in a suspended organization relationships: type: object properties: quota: $ref: '#/components/schemas/RelationshipToOne' description: The quota applied to the organization metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this organization domains: $ref: '#/components/schemas/Link' description: The URL to get the domains for this organization quota: $ref: '#/components/schemas/Link' description: The URL to get the quota for this organization default_domain: $ref: '#/components/schemas/Link' description: The URL to get the default domain for this organization description: | An org is a development account that an individual or multiple collaborators can own and use. All collaborators access an org with user accounts. Collaborators in an org share a resource quota plan, applications, services availability, and custom domains. OrganizationList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Organization' description: A paginated list of organizations OrganizationQuota: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the quota apps: type: object description: Quotas that affect applications and application sub-resources properties: per_process_memory_in_mb: type: - integer - 'null' description: Maximum memory for a single process or task total_memory_in_mb: type: - integer - 'null' description: Total memory allowed for all the started processes and running tasks in an organization total_instances: type: - integer - 'null' description: Total instances of all the started processes allowed in an organization log_rate_limit_in_bytes_per_second: type: - integer - 'null' description: Total log rate limit allowed for all the started processes and running tasks in an organization per_app_tasks: type: - integer - 'null' description: Maximum number of running tasks in an organization services: type: object description: Quotas that affect services properties: paid_services_allowed: type: boolean description: Specifies whether instances of paid service plans can be created total_service_instances: type: - integer - 'null' description: Total number of service instances allowed in an organization total_service_keys: type: - integer - 'null' description: Total number of service keys allowed in an organization routes: type: object description: Quotas that affect routes properties: total_routes: type: - integer - 'null' description: Total number of routes allowed in an organization total_reserved_ports: type: - integer - 'null' description: Total number of ports that are reservable by routes in an organization domains: type: object description: Quotas that affect domains properties: total_domains: type: - integer - 'null' description: Total number of domains that can be scoped to an organization relationships: type: object properties: organizations: $ref: '#/components/schemas/RelationshipToMany' description: A relationship to the organizations where the quota is applied metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this organization quota organizations: $ref: '#/components/schemas/Link' description: The URL to get the organizations for this quota description: | Organization quotas are named sets of memory, log rate, service, and instance usage quotas. For example, one organization quota might allow up to 10 services, 10 routes, and 2 GB of RAM, while another might offer 100 services, 100 routes, and 10 GB of RAM. OrganizationQuotaList: type: object allOf: - $ref: '#/components/schemas/Pagination' - properties: resources: type: array items: $ref: '#/components/schemas/OrganizationQuota' description: A paginated list of organization quotas Package: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: type: type: string description: Type of the package; valid values are bits or docker enum: - bits - docker data: type: object description: Data for package type properties: error: type: - string - 'null' description: If an error occurs this field will contain the error message checksum: type: object properties: type: type: string description: The checksum type, for example sha256 value: type: - string - 'null' description: The checksum value; this will be populated after bits are uploaded image: type: string description: The registry address of the image username: type: - string - 'null' description: The username for the image's registry password: type: - string - 'null' description: The password for the image's registry state: type: string description: State of the package; valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, or EXPIRED enum: - AWAITING_UPLOAD - PROCESSING_UPLOAD - READY - FAILED - COPYING - EXPIRED relationships: $ref: '#/components/schemas/Relationships' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this package upload: $ref: '#/components/schemas/Link' description: The URL to upload the package bits download: $ref: '#/components/schemas/Link' description: The URL to download the package bits app: $ref: '#/components/schemas/Link' description: The URL to get the app for this package description: A package represents an application"s "source code" - either raw bits or a pointer to these bits. Packages are used to create builds, which result in a droplet that can be deployed. PackageList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Package' Process: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: version: type: string format: uuid description: Random identifier that changes every time the process will be recreated in the runtime type: type: string description: Process type; a unique identifier for processes belonging to an app command: type: - string - 'null' description: The command used to start the process; use null to revert to the buildpack-detected or procfile-provided start command user: type: - string - 'null' description: The user used to run the process; use null to revert to the docker-detected or default 'vcap' user instances: type: integer description: The number of instances to run memory_in_mb: type: - integer - 'null' description: The memory in MB allocated per instance disk_in_mb: type: - integer - 'null' description: The disk in MB allocated per instance log_rate_limit_in_bytes_per_second: type: integer description: The log rate in bytes per second allocated per instance health_check: $ref: '#/components/schemas/HealthCheck' readiness_health_check: $ref: '#/components/schemas/HealthCheck' relationships: type: object properties: app: $ref: '#/components/schemas/RelationshipToOne' revision: oneOf: - $ref: '#/components/schemas/RelationshipToOne' - type: 'null' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this process scale: $ref: '#/components/schemas/Link' description: The URL to scale this process app: $ref: '#/components/schemas/Link' description: The URL to get the app for this process space: $ref: '#/components/schemas/Link' description: The URL to get the space for this process stats: $ref: '#/components/schemas/Link' description: The URL to get the stats for this process description: A process defines the runnable units of an app ProcessList: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: resources: type: array items: $ref: '#/components/schemas/Process' description: A list of processes ProcessStats: type: object properties: resources: type: array items: type: object properties: type: type: string index: type: integer state: type: string enum: - RUNNING - CRASHED - STARTING - DOWN - STOPPING host: type: string uptime: type: integer mem_quota: type: - integer - 'null' disk_quota: type: - integer - 'null' log_rate_limit: type: - integer - 'null' usage: type: object properties: time: type: string format: date-time cpu: type: number mem: type: integer disk: type: integer log_rate: type: integer description: Statistics for a process SecurityGroup: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the security group globally_enabled: type: object properties: running: type: boolean description: Whether the security group is globally enabled for running apps staging: type: boolean description: Whether the security group is globally enabled for staging apps rules: type: array items: type: object properties: protocol: type: string description: Protocol for the rule destination: type: string description: Destination for the rule ports: type: string description: Ports for the rule type: type: integer description: Type for ICMP rules code: type: integer description: Code for ICMP rules description: type: string description: Description of the rule description: Rules for the security group running_spaces: type: object properties: data: type: array items: $ref: '#/components/schemas/Relationship' description: Spaces where this security group is applied to running apps staging_spaces: type: object properties: data: type: array items: $ref: '#/components/schemas/Relationship' description: Spaces where this security group is applied to staging apps links: type: object properties: self: $ref: '#/components/schemas/Link' running_spaces: $ref: '#/components/schemas/Link' staging_spaces: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - name - globally_enabled - rules - links ServiceBroker: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the service broker url: type: string format: uri description: URL of the service broker relationships: type: object properties: space: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the service broker links: type: object properties: self: $ref: '#/components/schemas/Link' space: $ref: '#/components/schemas/Link' service_offerings: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - name - url - links AppCredentialBinding: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: type: type: string enum: - app description: Type of credential binding name: type: - string - 'null' description: Name of the credential binding last_operation: $ref: '#/components/schemas/ServiceCredentialBindingLastOperation' relationships: type: object properties: app: $ref: '#/components/schemas/RelationshipToOne' service_instance: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the credential binding links: type: object properties: self: $ref: '#/components/schemas/Link' details: $ref: '#/components/schemas/Link' app: $ref: '#/components/schemas/Link' service_instance: $ref: '#/components/schemas/Link' parameters: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter required: - type - relationships - links KeyCredentialBinding: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: type: type: string enum: - key description: Type of credential binding name: type: string description: Name of the credential binding last_operation: $ref: '#/components/schemas/ServiceCredentialBindingLastOperation' relationships: type: object properties: service_instance: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the credential binding links: type: object properties: self: $ref: '#/components/schemas/Link' details: $ref: '#/components/schemas/Link' service_instance: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter required: - type - relationships - links ManagedServiceInstance: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: type: type: string enum: - managed description: Type of service instance name: type: string description: Name of the service instance tags: type: array items: type: string description: Tags for the service instance syslog_drain_url: type: - string - 'null' format: uri description: URL for syslog drain route_service_url: type: - string - 'null' format: uri description: URL for route service dashboard_url: type: - string - 'null' format: uri description: URL for service dashboard maintenance_info: type: object properties: version: type: string description: Version of maintenance info description: type: - string - 'null' description: Description of maintenance info upgrade_available: type: boolean description: Whether an upgrade is available last_operation: $ref: '#/components/schemas/ServiceInstanceLastOperation' relationships: type: object properties: space: $ref: '#/components/schemas/RelationshipToOne' service_plan: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the service instance links: type: object properties: self: $ref: '#/components/schemas/Link' space: $ref: '#/components/schemas/Link' service_plan: $ref: '#/components/schemas/Link' parameters: $ref: '#/components/schemas/Link' service_credential_bindings: $ref: '#/components/schemas/Link' service_route_bindings: $ref: '#/components/schemas/Link' shared_spaces: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - type - name - relationships - links UserProvidedServiceInstance: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: type: type: string enum: - user-provided description: Type of service instance name: type: string description: Name of the service instance tags: type: array items: type: string description: Tags for the service instance syslog_drain_url: type: - string - 'null' format: uri description: URL for syslog drain route_service_url: type: - string - 'null' format: uri description: URL for route service relationships: type: object properties: space: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the service instance links: type: object properties: self: $ref: '#/components/schemas/Link' space: $ref: '#/components/schemas/Link' service_credential_bindings: $ref: '#/components/schemas/Link' service_route_bindings: $ref: '#/components/schemas/Link' credentials: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - type - name - relationships - links ServicePlanVisibility: type: object properties: type: type: string description: Type of visibility enum: - public - admin - organization - space organizations: type: array items: type: object properties: guid: type: string format: uuid description: Organization GUID name: type: string description: Organization name description: Organizations that have visibility to this service plan required: - type ServiceRouteBinding: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: route_service_url: type: - string - 'null' format: uri description: URL for the route service last_operation: $ref: '#/components/schemas/ServiceCredentialBindingLastOperation' relationships: type: object properties: route: $ref: '#/components/schemas/RelationshipToOne' service_instance: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the service route binding links: type: object properties: self: $ref: '#/components/schemas/Link' route: $ref: '#/components/schemas/Link' service_instance: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter required: - relationships - links Sidecar: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the sidecar command: type: string description: Command to run for the sidecar process_types: type: array items: type: string description: Process types that the sidecar applies to memory_in_mb: type: - integer - 'null' description: Memory limit for the sidecar in MB origin: type: - string - 'null' description: Origin of the sidecar enum: - user - buildpack relationships: type: object properties: app: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the sidecar links: type: object properties: self: $ref: '#/components/schemas/Link' app: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - name - command - process_types - relationships SpaceQuota: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the space quota apps: type: object properties: total_memory_in_mb: type: - integer - 'null' description: Total memory allowed for all apps in MB per_process_memory_in_mb: type: - integer - 'null' description: Maximum memory per process in MB log_rate_limit_in_bytes_per_second: type: - integer - 'null' description: Log rate limit in bytes per second total_instances: type: - integer - 'null' description: Total number of app instances allowed per_app_tasks: type: - integer - 'null' description: Maximum number of tasks per app description: App limits for the space quota services: type: object properties: paid_services_allowed: type: boolean description: Whether paid services are allowed total_service_instances: type: - integer - 'null' description: Total number of service instances allowed total_service_keys: type: - integer - 'null' description: Total number of service keys allowed description: Service limits for the space quota routes: type: object properties: total_routes: type: - integer - 'null' description: Total number of routes allowed total_reserved_ports: type: - integer - 'null' description: Total number of reserved ports allowed description: Route limits for the space quota relationships: type: object properties: organization: $ref: '#/components/schemas/RelationshipToOne' spaces: $ref: '#/components/schemas/RelationshipToMany' description: Relationships for the space quota links: type: object properties: self: $ref: '#/components/schemas/Link' organization: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - name - apps - services - routes - relationships - links Space: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the space relationships: type: object properties: organization: $ref: '#/components/schemas/RelationshipToOne' quota: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the space links: type: object properties: self: $ref: '#/components/schemas/Link' organization: $ref: '#/components/schemas/Link' features: $ref: '#/components/schemas/Link' apply_manifest: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter required: - name - relationships - links Stack: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the stack description: type: - string - 'null' description: Description of the stack build_rootfs_image: type: string description: The filesystem root image for building run_rootfs_image: type: string description: The filesystem root image for running default: type: boolean description: Whether this is the default stack links: type: object properties: self: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - name - description - links IndexLink: allOf: - $ref: '#/components/schemas/Link' - type: object properties: meta: type: object description: Contains metadata about the link properties: version: type: string description: The version of the API host_key_fingerprint: type: string description: The host key fingerprint of the link oauth_client: type: string description: The oauth client for the link description: | Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET. Can include a meta object with metadata about the link. Errors: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' description: | An error response will always return a list of error objects. Errors appear on the job resource for asynchronous operations. Clients should use the code and title fields for programmatically handling specific errors. The message in the detail field is subject to change over time. ServiceOffering: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: service_broker_guid: type: string service_broker_name: type: string metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this service offering service_plans: $ref: '#/components/schemas/Link' description: The URL to get the service plans for this offering service_broker: $ref: '#/components/schemas/Link' description: The URL to get the service broker for this offering ServiceInstanceLastOperation: type: object properties: type: type: string description: Type of the last operation enum: - create - update - delete state: type: string description: State of the last operation enum: - initial - in progress - succeeded - failed description: type: - string - 'null' description: A textual explanation associated with this state created_at: type: string format: date-time description: When the last operation was created updated_at: type: string format: date-time description: When the last operation was last updated description: The last operation object for service instances BuildUpdate: type: object properties: state: type: string description: State of the build enum: - STAGING - STAGED - FAILED staging_memory_in_mb: type: - integer - 'null' description: Memory in MB allocated for staging of the build staging_disk_in_mb: type: - integer - 'null' description: Disk space in MB allocated for staging of the build staging_log_rate_limit_bytes_per_second: type: integer description: Log rate limit in bytes per second allocated for staging of the build error: type: - string - 'null' description: A string describing errors during the build process lifecycle: $ref: '#/components/schemas/Lifecycle' description: Provides the lifecycle object to use during staging metadata: $ref: '#/components/schemas/Metadata' ResourceMatch: type: object properties: resources: type: array items: type: object properties: checksum: type: object properties: value: type: string size_in_bytes: type: integer path: type: string mode: type: string Revision: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: version: type: integer description: Version number of the revision description: type: - string - 'null' description: Description of the revision, created by the user droplet: $ref: '#/components/schemas/RelationshipToOne' relationships: allOf: - $ref: '#/components/schemas/Relationships' - properties: app: $ref: '#/components/schemas/RelationshipToOne' enabled: type: boolean description: Whether the revision is enabled or not. metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this revision app: $ref: '#/components/schemas/Link' description: The URL to get the app for this revision environment_variables: $ref: '#/components/schemas/Link' description: The URL to get the environment variables for this revision description: An App Revision is an immutable snapshot of an app at a particular point in time. Revisions are identified by a sequential version number. The "current" revision for an app is the revision that is currently deployed for all instances of the app. RevisionList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Revision' Role: allOf: - $ref: '#/components/schemas/BaseSchema' type: object properties: type: type: string description: |- Role type. Possible values are: - `organization_user`: A user in the organization - `organization_auditor`: An auditor in the organization - `organization_manager`: A manager in the organization - `organization_billing_manager`: A billing manager in the organization - `space_auditor`: An auditor in the space - `space_developer`: A developer in the space - `space_manager`: A manager in the space - `space_supporter`: A supporter in the space (not authorized to use the V2 API) enum: - organization_user - organization_auditor - organization_manager - organization_billing_manager - space_auditor - space_developer - space_manager - space_supporter relationships: allOf: - $ref: '#/components/schemas/Relationships' properties: organization: allOf: - $ref: '#/components/schemas/RelationshipToOne' - description: | A relationship to the organization the role controls access to; when this is a space role, `organization.data` will be `null`. space: allOf: - $ref: '#/components/schemas/RelationshipToOne' - description: | A relationship to the space the role controls access to; when this is an organization role, `space.data` will be `null`. user: allOf: - $ref: '#/components/schemas/UserRelationshipToOne' - description: | A relationship to the user; this is the user that has the role links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this role user: $ref: '#/components/schemas/Link' description: The URL to get the user for this role organization: $ref: '#/components/schemas/Link' description: The URL to get the organization for this role space: $ref: '#/components/schemas/Link' description: The URL to get the space for this role included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter description: | Roles represent a set of permissions that can be granted to users. Roles are represented as a JSON object. A role consists of several required role fields and other attributes specific to the role. See Roles for specific roles. SecurityGroupList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/SecurityGroup' SecurityGroupCreate: type: object properties: name: type: string description: Name of the security group globally_enabled: type: object properties: running: type: boolean description: Whether the security group is globally enabled for running apps staging: type: boolean description: Whether the security group is globally enabled for staging apps rules: type: array items: type: object properties: protocol: type: string description: Protocol for the rule destination: type: string description: Destination for the rule ports: type: string description: Ports for the rule type: type: integer description: Type for ICMP rules code: type: integer description: Code for ICMP rules description: type: - string - 'null' description: Description of the rule description: Rules for the security group metadata: $ref: '#/components/schemas/Metadata' required: - name SecurityGroupUpdate: type: object properties: name: type: string description: Name of the security group globally_enabled: type: object properties: running: type: boolean description: Whether the security group is globally enabled for running apps staging: type: boolean description: Whether the security group is globally enabled for staging apps rules: type: array items: type: object properties: protocol: type: string description: Protocol for the rule destination: type: string description: Destination for the rule ports: type: string description: Ports for the rule type: type: integer description: Type for ICMP rules code: type: integer description: Code for ICMP rules description: type: - string - 'null' description: Description of the rule description: Rules for the security group metadata: $ref: '#/components/schemas/Metadata' ServiceBrokerList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/ServiceBroker' ServiceCredentialBindingLastOperation: type: object properties: type: type: string description: Type of the last operation enum: - create - delete state: type: string description: State of the last operation enum: - initial - in progress - succeeded - failed description: type: - string - 'null' description: A textual explanation associated with this state created_at: type: string format: date-time description: When the last operation was created updated_at: type: string format: date-time description: When the last operation was last updated description: The last operation object for service credential bindings ServiceCredentialBindingList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: oneOf: - $ref: '#/components/schemas/AppCredentialBinding' - $ref: '#/components/schemas/KeyCredentialBinding' discriminator: propertyName: type mapping: app: '#/components/schemas/AppCredentialBinding' key: '#/components/schemas/KeyCredentialBinding' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter ServiceInstanceList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: oneOf: - $ref: '#/components/schemas/ManagedServiceInstance' - $ref: '#/components/schemas/UserProvidedServiceInstance' discriminator: propertyName: type mapping: managed: '#/components/schemas/ManagedServiceInstance' user-provided: '#/components/schemas/UserProvidedServiceInstance' ServiceOfferingList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/ServiceOffering' ServicePlan: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: service_offering_guid: type: string service_offering_name: type: string metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this service plan service_offering: $ref: '#/components/schemas/Link' description: The URL to get the service offering for this plan visibility: $ref: '#/components/schemas/Link' description: The URL to get the visibility for this plan included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter ServicePlanList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/ServicePlan' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter ServiceRouteBindingList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/ServiceRouteBinding' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter ServiceRouteBindingCreate: type: object properties: relationships: type: object properties: route: $ref: '#/components/schemas/RelationshipToOne' description: The route to bind service_instance: $ref: '#/components/schemas/RelationshipToOne' description: The service instance to bind required: - route - service_instance description: Relationships for the service route binding parameters: type: object description: A JSON object that is passed to the service broker metadata: $ref: '#/components/schemas/Metadata' required: - relationships ServiceUsageEvent: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this service usage event ServiceUsageEventList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/ServiceUsageEvent' SidecarList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Sidecar' SpaceList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Space' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter SpaceFeature: type: object properties: name: type: string description: type: - string - 'null' enabled: type: boolean UserList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/User' SpaceQuotaList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/SpaceQuota' StackList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Stack' Task: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string command: type: string state: type: string enum: - PENDING - RUNNING - SUCCEEDED - FAILED - CANCELING sequence_id: type: integer memory_in_mb: type: - integer - 'null' disk_in_mb: type: - integer - 'null' droplet_guid: type: string result: type: object properties: failure_reason: type: - string - 'null' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: A task is a one-off process that can be run in the Cloud Foundry environment. TaskList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Task' HealthCheck: type: object properties: type: type: string enum: - port - process - http description: The type of health check to perform; valid values are http, port, and process; default is port data: type: object properties: timeout: type: - integer - 'null' description: The duration in seconds that health checks can fail before the process is restarted invocation_timeout: type: - integer - 'null' description: The timeout in seconds for individual health check requests for http and port health checks interval: type: - integer - 'null' description: The interval in seconds between health check requests endpoint: type: string description: The endpoint called to determine if the app is healthy; this key is only present for http health checks description: Health check configuration for a process RouteList: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Route' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter description: A list of routes securitySchemes: oauth: type: oauth2 flows: implicit: authorizationUrl: https://uaa.cloudfoundry.local/api-oauth/dialog scopes: cloud_controller.admin: This scope provides read and write access to all resources cloud_controller.admin_read_only: This scope provides read only access to all resources cloud_controller.global_auditor: This scope provides read access to all resources cloud_controller.read: Read access to the Cloud Controller cloud_controller.write: Write access to the Cloud Controller cloud_controller.update_build_state: This scope allows its bearer to update the state of a build; currently only used when updating builds cloud_controller_service_permissions.read: This scope provides read only access for service instance permissions bearer: type: http scheme: bearer bearerFormat: JWT description: Bearer JWT token authentication parameters: GUID: $ref: '#/components/parameters/Guid' guid: $ref: '#/components/parameters/Guid' Page: name: page in: query required: false schema: type: integer description: Page to display; valid values are integers >= 1 example: 1 PerPage: name: per_page in: query required: false schema: type: integer description: Number of results per page, valid values are 1 through 5000 example: 50 OrderBy: name: order_by in: query required: false schema: type: string description: | Value to sort by. Defaults to ascending; prepend with `-` to sort descending. example: created_at CreatedAts: name: created_ats in: query required: false schema: type: string description: | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators). example: '2021-01-01T00:00:00Z' UpdatedAts: name: updated_ats in: query required: false schema: type: string description: | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators). example: '2021-01-01T00:00:00Z' LabelSelector: name: label_selector in: query description: A query string containing a list of [label selector](#labels-and-selectors) requirements required: false schema: type: string example: environment=production Guid: name: guid in: path required: true schema: type: string format: uuid description: The unique identifier for the resource SpaceGuid: name: space_guid in: path required: true schema: type: string format: uuid description: The unique identifier for the space UserGuid: name: guid in: path required: true schema: type: string description: The unique identifier for the user, matching either a UAA user id or client id. A client id may not be a uuid. responses: '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Errors' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Errors' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Errors' BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Errors' text/html: schema: type: string NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Errors' UnprocessableEntity: description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Errors' BuildpackCreateResponse: description: Successfully created buildpack content: application/json: schema: $ref: '#/components/schemas/Buildpack' BuildpackGetResponse: description: Successfully retrieved buildpack content: application/json: schema: $ref: '#/components/schemas/Buildpack' UserCreateResponse: description: User created content: application/json: schema: $ref: '#/components/schemas/User' UserUpdateResponse: description: User updated content: application/json: schema: $ref: '#/components/schemas/User' DropletCreateResponse: description: Successfully created droplet content: application/json: schema: $ref: '#/components/schemas/Droplet' DropletGetResponse: description: Successfully retrieved droplet content: application/json: schema: $ref: '#/components/schemas/Droplet' RouteCreateResponse: description: Route created content: application/json: schema: $ref: '#/components/schemas/Route' RouteListResponse: description: A list of routes content: application/json: schema: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Route' RoleCreateResponse: description: Role created content: application/json: schema: $ref: '#/components/schemas/Role' RoleGetResponse: description: Role retrieved content: application/json: schema: $ref: '#/components/schemas/Role' RoleListResponse: description: Roles retrieved content: application/json: schema: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Role' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/Errors' BadGateway: description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/Errors' TooManyRequests: description: Too Many Requests content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: integer example: 10008 title: type: string example: CF-RateLimitExceeded detail: type: string example: Rate limit exceeded requestBodies: AppCreateRequestBody: description: App object that needs to be created required: true content: application/json: schema: type: object properties: name: type: string description: Name of the app environment_variables: type: object description: Environment variables to be used for the App when running additionalProperties: type: string lifecycle: $ref: '#/components/schemas/Lifecycle' description: Provides the lifecycle object for the application relationships: type: object properties: space: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to a space required: - space metadata: $ref: '#/components/schemas/Metadata' required: - name - relationships description: Request schema for creating an app examples: default: summary: default value: name: my_app relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 AppUpdateRequestBody: description: App object that needs to be updated required: true content: application/json: schema: type: object properties: name: type: string description: Name of the app environment_variables: type: object description: Environment variables to be used for the App when running additionalProperties: type: string lifecycle: $ref: '#/components/schemas/Lifecycle' description: 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. metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating an app examples: default: summary: default value: name: my_app lifecycle: type: buildpack data: buildpacks: - java_buildpack BuildCreateRequestBody: description: Build object that needs to be created required: true content: application/json: schema: type: object properties: package: type: object properties: guid: type: string format: uuid required: - guid description: App package to stage lifecycle: $ref: '#/components/schemas/Lifecycle' description: Lifecycle information for a build metadata: $ref: '#/components/schemas/Metadata' required: - package description: Request schema for creating a build BuildpackCreateRequestBody: description: Buildpack object that needs to be added required: true content: application/json: schema: type: object properties: name: type: string description: The name of the buildpack stack: type: string description: The name of the stack that the buildpack will use position: type: integer description: The order in which the buildpacks are checked during buildpack auto-detection lifecycle: type: string description: The version of buildpack the buildpack will use. `buildpack` indicates [Classic Buildpacks](https://docs.cloudfoundry.org/buildpacks/classic.html). `cnb` indicates [Cloud Native Buildpacks](https://docs.cloudfoundry.org/buildpacks/cnb/) enabled: type: boolean description: Whether or not the buildpack will be used for staging locked: type: boolean description: Whether or not the buildpack is locked to prevent updating the bits metadata: $ref: '#/components/schemas/Metadata' required: - name description: Request schema for creating a buildpack examples: default: summary: default value: name: ruby_buildpack position: 42 enabled: true locked: false stack: windows64 BuildpackUpdateRequestBody: description: Buildpack object that needs to be updated required: true content: application/json: schema: type: object properties: name: type: string description: The name of the buildpack position: type: integer description: The order in which the buildpacks are checked during buildpack auto-detection enabled: type: boolean description: Whether or not the buildpack will be used for staging locked: type: boolean description: Whether or not the buildpack is locked to prevent updating the bits stack: type: string description: The name of the stack that the buildpack will use metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a buildpack examples: default: summary: default value: name: ruby_buildpack position: 42 enabled: true locked: false stack: windows64 DomainCreateRequestBody: description: Domain object that needs to be created required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Name of the domain internal: type: boolean description: Whether the domain is used for internal (container-to-container) traffic router_group: type: object properties: guid: type: string format: uuid description: '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_' relationships: type: object properties: organization: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to the organization the domain will be scoped to; _note cannot be used when `internal` is set to `true` or domain is associated with a router group_ shared_organizations: $ref: '#/components/schemas/RelationshipToMany' description: A relationship to organizations the domain will be shared with _Note cannot be used without an organization relationship_ metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: name: example.com internal: false DomainUpdateRequestBody: description: Domain object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a domain DropletCreateRequestBody: description: Droplet object that needs to be created required: true content: application/json: schema: type: object properties: relationships: type: object properties: app: $ref: '#/components/schemas/RelationshipToOne' description: App to create droplet for required: - app process_types: type: object description: Process names and start commands for the droplet metadata: $ref: '#/components/schemas/Metadata' required: - relationships description: Request schema for creating a droplet examples: default: summary: default value: relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 process_types: rake: bundle exec rake web: bundle exec rackup config.ru -p $PORT IsolationSegmentCreate: description: Isolation segment to create content: application/json: schema: type: object properties: name: type: string description: Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness metadata: $ref: '#/components/schemas/Metadata' required: - name examples: default: summary: default value: name: my_segment OrganizationCreateRequestBody: description: Organization object that needs to be created required: true content: application/json: schema: type: object properties: name: type: string description: Organization name suspended: type: boolean description: Whether an organization is suspended or not metadata: $ref: '#/components/schemas/Metadata' required: - name description: Request schema for creating an organization examples: default: summary: default value: name: my-organization OrganizationUpdateRequestBody: description: Organization object that needs to be updated required: true content: application/json: schema: type: object properties: name: type: string description: Organization name suspended: type: boolean description: Whether an organization is suspended or not metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating an organization examples: default: summary: default value: name: my-organization OrganizationQuotaCreateRequestBody: description: Organization quota object that needs to be created required: true content: application/json: schema: type: object properties: name: type: string description: Name of the quota apps: type: object description: Quotas that affect applications and application sub-resources properties: per_process_memory_in_mb: type: - integer - 'null' description: Maximum memory for a single process or task total_memory_in_mb: type: - integer - 'null' description: Total memory allowed for all the started processes and running tasks in an organization total_instances: type: - integer - 'null' description: Total instances of all the started processes allowed in an organization log_rate_limit_in_bytes_per_second: type: - integer - 'null' description: Total log rate limit allowed for all the started processes and running tasks in an organization per_app_tasks: type: - integer - 'null' description: Maximum number of running tasks in an organization services: type: object description: Quotas that affect services properties: paid_services_allowed: type: boolean description: Specifies whether instances of paid service plans can be created total_service_instances: type: - integer - 'null' description: Total number of service instances allowed in an organization total_service_keys: type: - integer - 'null' description: Total number of service keys allowed in an organization routes: type: object description: Quotas that affect routes properties: total_routes: type: - integer - 'null' description: Total number of routes allowed in an organization total_reserved_ports: type: - integer - 'null' description: Total number of ports that are reservable by routes in an organization domains: type: object description: Quotas that affect domains properties: total_domains: type: - integer - 'null' description: Total number of domains that can be scoped to an organization relationships: type: object properties: organizations: $ref: '#/components/schemas/RelationshipToMany' description: A relationship to the organizations where the quota is applied metadata: $ref: '#/components/schemas/Metadata' required: - name description: Request schema for creating an organization quota examples: default: summary: default value: name: production OrganizationQuotaUpdateRequestBody: description: Organization quota object that needs to be updated required: true content: application/json: schema: type: object properties: name: type: string description: Name of the quota apps: type: object description: Quotas that affect applications and application sub-resources properties: per_process_memory_in_mb: type: - integer - 'null' description: Maximum memory for a single process or task total_memory_in_mb: type: - integer - 'null' description: Total memory allowed for all the started processes and running tasks in an organization total_instances: type: - integer - 'null' description: Total instances of all the started processes allowed in an organization log_rate_limit_in_bytes_per_second: type: - integer - 'null' description: Total log rate limit allowed for all the started processes and running tasks in an organization per_app_tasks: type: - integer - 'null' description: Maximum number of running tasks in an organization services: type: object description: Quotas that affect services properties: paid_services_allowed: type: boolean description: Specifies whether instances of paid service plans can be created total_service_instances: type: - integer - 'null' description: Total number of service instances allowed in an organization total_service_keys: type: - integer - 'null' description: Total number of service keys allowed in an organization routes: type: object description: Quotas that affect routes properties: total_routes: type: - integer - 'null' description: Total number of routes allowed in an organization total_reserved_ports: type: - integer - 'null' description: Total number of ports that are reservable by routes in an organization domains: type: object description: Quotas that affect domains properties: total_domains: type: - integer - 'null' description: Total number of domains that can be scoped to an organization metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating an organization quota PackageCreateRequestBody: description: 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. required: true content: application/json: schema: type: object properties: type: type: string description: 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). enum: - bits - docker data: type: object description: Data for package type properties: image: type: string description: The registry address of the image (for docker packages) username: type: string description: The username for the image's registry (for docker packages) password: type: string description: The password for the image's registry (for docker packages) relationships: type: object properties: app: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to an app required: - app metadata: $ref: '#/components/schemas/Metadata' required: - relationships description: Request schema for creating a package examples: buildpack_app: summary: buildpack app value: type: bits relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 docker_app: summary: Docker app value: type: docker relationships: app: data: guid: 123e4567-e89b-12d3-a456-426614174000 data: image: registry/image:latest username: username password: password PackageUpdateRequestBody: description: Package object that needs to be updated required: true content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' username: type: string description: The username for the image’s registry. Only possible for Docker package. password: type: string description: The password for the image’s registry. Only possible for Docker package. description: Request schema for updating a package PackageUploadRequestBody: description: Package bits to be uploaded required: true content: multipart/form-data: schema: type: object properties: bits: type: string format: binary resources: type: array items: $ref: '#/components/schemas/ResourceMatch' ProcessUpdateRequestBody: description: Process object that needs to be updated required: true content: application/json: schema: type: object properties: command: type: - string - 'null' description: The command used to start the process; use null to revert to the buildpack-detected or procfile-provided start command health_check: $ref: '#/components/schemas/HealthCheck' description: The health check to perform on the process readiness_health_check: $ref: '#/components/schemas/HealthCheck' description: The readiness health check to perform on the process metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a process examples: default: summary: default value: command: rackup metadata: labels: key: value annotations: note: detailed information RoleCreate: description: Role to create content: application/json: schema: type: object properties: type: type: string description: Role to create enum: - organization_user - organization_auditor - organization_manager - organization_billing_manager - space_auditor - space_developer - space_manager - space_supporter relationships: type: object properties: user: $ref: '#/components/schemas/UserRelationshipToOne' organization: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to an organization; required only when creating an organization role space: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to a space; required only when creating a space role examples: by_user_guid: summary: by user guid value: type: organization_auditor relationships: user: data: guid: 123e4567-e89b-12d3-a456-426614174000 organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 by_username_and_origin: summary: by username and origin value: type: organization_auditor relationships: user: data: username: user-name origin: ldap organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 RouteCreateRequestBody: description: Route to create content: application/json: schema: type: object properties: host: type: string description: The host component for the route; not compatible with routes specifying the `tcp` protocol path: type: string description: The path component for the route; should begin with a `/` and not compatible with routes specifying the `tcp` protocol port: type: integer description: 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 relationships: type: object properties: domain: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to the domain of the route space: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to the space containing the route; routes can only be mapped to destinations in that space metadata: $ref: '#/components/schemas/Metadata' required: - relationships examples: default: summary: default value: host: a-hostname path: /some_path port: 6666 relationships: domain: data: guid: 123e4567-e89b-12d3-a456-426614174000 space: data: guid: 123e4567-e89b-12d3-a456-426614174000 options: loadbalancing: round-robin metadata: labels: key: value annotations: note: detailed information RouteDestinations: description: A list of route destinations content: application/json: schema: type: object properties: destinations: type: array items: $ref: '#/components/schemas/RouteDestination' description: List of destinations to add to route; destinations without `process.type` specified will get process type `"web"` by default examples: default: summary: default value: destinations: - app: guid: 123e4567-e89b-12d3-a456-426614174000 weight: 61 - app: guid: 123e4567-e89b-12d3-a456-426614174000 process: type: api weight: 39 port: 9000 protocol: http1 SpaceCreateRequestBody: description: Space object that needs to be created required: true content: application/json: schema: type: object properties: name: type: string description: Name of the space relationships: type: object properties: organization: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to an organization required: - organization metadata: $ref: '#/components/schemas/Metadata' required: - name - relationships description: Request schema for creating a space examples: default: summary: default value: name: my-space relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 SpaceUpdateRequestBody: description: Space object that needs to be updated required: true content: application/json: schema: type: object properties: name: type: string description: New space name metadata: $ref: '#/components/schemas/Metadata' description: Request schema for updating a space examples: default: summary: default value: name: new-space-name TaskCreateRequestBody: description: Task object that needs to be created required: true content: application/json: schema: type: object properties: command: type: string description: The command to run for the task. **NOTE:** optional if a `template.process.guid` is provided name: type: string description: Human-readable name for the task memory_in_mb: type: integer description: Amount of memory to allocate for the task in MB disk_in_mb: type: integer description: Amount of disk to allocate for the task in MB log_rate_limit_in_bytes_per_second: type: integer description: Amount of log rate limit to allocate for the task in bytes per second droplet_guid: type: string format: uuid description: The GUID of a droplet to use to run the task template: type: object description: An object with a process field to template the task from properties: process: type: object properties: guid: type: string format: uuid required: - guid description: The guid of the process that will be used as a template metadata: $ref: '#/components/schemas/Metadata' description: Request schema for creating a task examples: default: summary: default value: template: process: guid: 123e4567-e89b-12d3-a456-426614174000 UserCreate: description: User to create content: application/json: schema: type: object properties: guid: type: string description: Unique identifier for the user username: type: string description: Username of the user to be created. This can only be provided together with origin origin: type: string description: Origin of the user to be created. This can only be provided together with username and cannot be uaa metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 by_username_and_origin: summary: by username and origin value: username: some-user origin: some-origin UserUpdate: description: User to update content: application/json: schema: type: object properties: username: type: string description: The username of the user presentation_name: type: string description: The presentation name of the user origin: type: string description: The origin of the user metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this user examples: default: summary: default value: metadata: labels: environment: production annotations: note: detailed information rate_limits: custom_request_limit: 2000 ServiceBrokerCreate: description: Service broker to create content: application/json: schema: type: object properties: name: type: string description: Name of the service broker url: type: string format: uri description: URL of the service broker authentication: type: object properties: type: type: string enum: - basic description: Type of authentication credentials: type: object properties: username: type: string password: type: string required: - username - password required: - type - credentials description: Authentication details for the service broker relationships: type: object properties: space: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the service broker metadata: $ref: '#/components/schemas/Metadata' required: - name - url examples: default: summary: default value: name: my_service_broker url: https://example.service-broker.com authentication: type: basic credentials: username: us3rn4me password: p4ssw0rd relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 SpaceQuotaCreate: description: Space quota to create content: application/json: schema: type: object properties: name: type: string description: Name of the space quota apps: type: object properties: total_memory_in_mb: type: integer description: Total memory allowed for all apps in MB per_process_memory_in_mb: type: integer description: Maximum memory per process in MB log_rate_limit_in_bytes_per_second: type: integer description: Log rate limit in bytes per second total_instances: type: integer description: Total number of app instances allowed per_app_tasks: type: integer description: Maximum number of tasks per app description: App limits for the space quota services: type: object properties: paid_services_allowed: type: boolean description: Whether paid services are allowed total_service_instances: type: integer description: Total number of service instances allowed total_service_keys: type: integer description: Total number of service keys allowed description: Service limits for the space quota routes: type: object properties: total_routes: type: integer description: Total number of routes allowed total_reserved_ports: type: integer description: Total number of reserved ports allowed description: Route limits for the space quota relationships: type: object properties: organization: $ref: '#/components/schemas/RelationshipToOne' spaces: $ref: '#/components/schemas/RelationshipToMany' description: Relationships for the space quota metadata: $ref: '#/components/schemas/Metadata' required: - name examples: default: summary: default value: name: production relationships: organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 SpaceQuotaUpdate: description: Space quota to update content: application/json: schema: type: object properties: name: type: string description: Name of the space quota apps: type: object properties: total_memory_in_mb: type: integer description: Total memory allowed for all apps in MB per_process_memory_in_mb: type: integer description: Maximum memory per process in MB log_rate_limit_in_bytes_per_second: type: integer description: Log rate limit in bytes per second total_instances: type: integer description: Total number of app instances allowed per_app_tasks: type: integer description: Maximum number of tasks per app description: App limits for the space quota services: type: object properties: paid_services_allowed: type: boolean description: Whether paid services are allowed total_service_instances: type: integer description: Total number of service instances allowed total_service_keys: type: integer description: Total number of service keys allowed description: Service limits for the space quota routes: type: object properties: total_routes: type: integer description: Total number of routes allowed total_reserved_ports: type: integer description: Total number of reserved ports allowed description: Route limits for the space quota metadata: $ref: '#/components/schemas/Metadata' UserProvidedServiceInstanceUpdate: description: User provided service instance to update content: application/json: schema: type: object properties: name: type: string description: Name of the service instance tags: type: array items: type: string description: Tags for the service instance credentials: type: object description: Service credentials syslog_drain_url: type: string format: uri description: URL for syslog drain route_service_url: type: string format: uri description: URL for route service metadata: $ref: '#/components/schemas/Metadata' ManagedServiceInstanceUpdate: description: Managed service instance to update content: application/json: schema: type: object properties: name: type: string description: Name of the service instance tags: type: array items: type: string description: Tags for the service instance parameters: type: object description: Parameters for the service instance relationships: type: object properties: service_plan: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the service instance metadata: $ref: '#/components/schemas/Metadata' SidecarCreate: description: Sidecar to create content: application/json: schema: type: object properties: name: type: string description: Name of the sidecar command: type: string description: Command to run for the sidecar process_types: type: array items: type: string description: Process types that the sidecar applies to memory_in_mb: type: integer description: Memory limit for the sidecar in MB examples: default: summary: default value: name: auth-sidecar command: bundle exec rackup process_types: - web - worker memory_in_mb: 300 ServiceBrokerUpdateRequestBody: description: Service broker object that needs to be updated required: true content: application/json: schema: type: object properties: name: type: string description: Name of the service broker url: type: string description: URL of the service broker authentication: type: object description: Credentials used to authenticate against the service broker properties: type: type: string enum: - basic description: Authentication type credentials: type: object description: Authentication credentials properties: username: type: string description: Username for basic authentication password: type: string description: Password for basic authentication required: - username - password required: - type - credentials metadata: $ref: '#/components/schemas/Metadata' examples: default: summary: default value: name: my_service_broker url: https://example.service-broker.com authentication: type: basic credentials: username: us3rn4me password: p4ssw0rd metadata: labels: key: value annotations: note: detailed information ServiceCredentialBindingCreateRequestBody: description: A request to create a service credential binding content: application/json: schema: type: object required: - type - relationships properties: type: type: string enum: - app - key description: Type of the service credential binding. Valid values are key and app name: type: string description: Name of the service credential binding. name is optional when the type is app relationships: type: object required: - service_instance properties: service_instance: $ref: '#/components/schemas/RelationshipToOne' description: The service instance to be bound app: $ref: '#/components/schemas/RelationshipToOne' description: The app to be bound. Required when type is app description: Relationships for the service credential binding parameters: type: object description: A JSON object that is passed to the service broker metadata: $ref: '#/components/schemas/Metadata' examples: app_credential_binding: summary: App credential binding value: type: app name: some-binding-name relationships: service_instance: data: guid: 7304bc3c-7010-11ea-8840-48bf6bec2d78 app: data: guid: e0e4417c-74ee-11ea-a604-48bf6bec2d78 parameters: key1: value1 key2: value2 metadata: labels: foo: bar annotations: baz: qux key_credential_binding: summary: Key credential binding value: type: key name: some-binding-name relationships: service_instance: data: guid: 7304bc3c-7010-11ea-8840-48bf6bec2d78 parameters: key1: value1 key2: value2 metadata: labels: foo: bar annotations: baz: qux default: summary: default value: type: key name: some-binding-name relationships: service_instance: data: guid: 123e4567-e89b-12d3-a456-426614174000 parameters: key1: value1 key2: value2 metadata: labels: foo: bar annotations: baz: qux ServiceCredentialBindingUpdateRequestBody: description: A request to update a service credential binding content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/Metadata' examples: update_binding: summary: Update service credential binding value: metadata: labels: foo: bar annotations: baz: qux default: summary: default value: metadata: labels: foo: bar annotations: baz: qux ServiceInstanceCreateRequestBody: description: A request to create a service instance content: application/json: schema: type: object required: - type - name - relationships properties: type: type: string enum: - managed - user-provided description: The type of service instance name: type: string description: Name of the service instance parameters: type: object description: A JSON object that is passed to the service broker credentials: type: object description: A JSON object that is made available to apps bound to this service instance (user-provided services only) tags: type: array items: type: string description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env syslog_drain_url: type: string description: URL to which logs for bound applications will be streamed (user-provided services only) route_service_url: type: string description: URL to which requests for bound routes will be forwarded; must use the https protocol (user-provided services only) relationships: type: object required: - space properties: space: $ref: '#/components/schemas/RelationshipToOne' description: The space in which to create the service instance service_plan: $ref: '#/components/schemas/RelationshipToOne' description: The service plan from which to create the service instance description: Relationships for the service instance metadata: $ref: '#/components/schemas/Metadata' examples: managed_service_instance: summary: Managed service instance value: type: managed name: my_service_instance parameters: foo: bar baz: qux tags: - foo - bar - baz metadata: annotations: foo: bar labels: baz: qux relationships: space: data: guid: 7304bc3c-7010-11ea-8840-48bf6bec2d78 service_plan: data: guid: e0e4417c-74ee-11ea-a604-48bf6bec2d78 user_provided_service_instance: summary: User-provided service instance value: type: user-provided name: my_service_instance credentials: foo: bar baz: qux tags: - foo - bar - baz syslog_drain_url: https://syslog.com/drain route_service_url: https://route.com/service metadata: annotations: foo: bar labels: baz: qux relationships: space: data: guid: 7304bc3c-7010-11ea-8840-48bf6bec2d78 default: summary: default value: type: user-provided name: my_service_instance credentials: foo: bar baz: qux tags: - foo - bar - baz syslog_drain_url: https://syslog.com/drain route_service_url: https://route.com/service metadata: annotations: foo: bar labels: baz: qux relationships: space: data: guid: 123e4567-e89b-12d3-a456-426614174000 ServiceInstanceUpdateRequestBody: description: A request to update a service instance content: application/json: schema: type: object properties: name: type: string description: Name of the service instance parameters: type: object description: A JSON object that is passed to the service broker (managed services only) credentials: type: object description: A JSON object that is made available to apps bound to this service instance (user-provided services only) tags: type: array items: type: string description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env syslog_drain_url: type: string description: URL to which logs for bound applications will be streamed (user-provided services only) route_service_url: type: string description: URL to which requests for bound routes will be forwarded; must use the https protocol (user-provided services only) relationships: type: object properties: service_plan: $ref: '#/components/schemas/RelationshipToOne' description: The service plan from which to create the service instance description: Relationships for the service instance maintenance_info: type: object required: - version properties: version: type: string description: 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 description: If provided, must have the `version` field; `version` must be a semantic version value and it must match the `version` in the `maintenance_info` for the service instance plan in the updated broker catalog. Any other value for `version` will cause a `MaintenanceInfoConflict` error metadata: $ref: '#/components/schemas/Metadata' examples: managed_service_instance: summary: Update managed service instance value: name: my_service_instance parameters: foo: bar baz: qux tags: - foo - bar - baz relationships: service_plan: data: guid: f2b6ba9c-a4d2-11ea-8ae6-48bf6bec2d78 metadata: annotations: note: detailed information labels: key: value managed_service_instance_upgrade: summary: Upgrade managed service instance value: maintenance_info: version: 2.1.1 user_provided_service_instance: summary: Update user-provided service instance value: name: my_service_instance credentials: foo: bar baz: qux tags: - foo - bar - baz syslog_drain_url: https://syslog.com/drain route_service_url: https://route.com/service metadata: annotations: foo: bar labels: baz: qux default: summary: default value: name: my_service_instance credentials: foo: bar baz: qux tags: - foo - bar - baz syslog_drain_url: https://syslog.com/drain route_service_url: https://route.com/service metadata: annotations: foo: bar labels: baz: qux ServicePlanVisibilityCreateRequestBody: description: Service plan visibility object that needs to be created required: true content: application/json: schema: type: object properties: type: type: string enum: - public - admin - organization description: Denotes the visibility of the plan organizations: type: array items: type: object properties: guid: type: string format: uuid required: - guid description: Desired list of organizations GUIDs where the plan will be accessible; required if type is organization required: - type examples: default: summary: default value: type: organization organizations: - guid: 123e4567-e89b-12d3-a456-426614174000 ServicePlanVisibilityUpdateRequestBody: description: Service plan visibility object that needs to be updated required: true content: application/json: schema: type: object properties: type: type: string enum: - public - admin - organization description: Denotes the visibility of the plan organizations: type: array items: type: object properties: guid: type: string format: uuid required: - guid description: Desired list of organizations GUIDs where the plan will be accessible; required if type is organization required: - type SidecarUpdateRequestBody: description: Sidecar object that needs to be updated required: true content: application/json: schema: type: object properties: name: type: string description: Human-readable name for the sidecar command: type: string description: The command used to start the sidecar process_types: type: array items: type: string description: A list of process types the sidecar applies to memory_in_mb: type: integer description: Reserved memory for sidecar examples: default: summary: default value: name: auth-sidecar command: bundle exec rackup process_types: - web - worker memory_in_mb: 300 StackCreateRequestBody: description: Stack object that needs to be created required: true content: application/json: schema: type: object properties: name: type: string description: Name of the stack; must be unique and no longer than 250 characters maxLength: 250 description: type: - string - 'null' description: Description of the stack; must no longer than 250 characters maxLength: 250 metadata: $ref: '#/components/schemas/Metadata' required: - name