openapi: 3.2.0 info: title: Cloud Foundry V3 Tasks API description: '# Welcome to the Experimental Cloud Foundry V3 API Docs!' 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: Tasks description: Tasks are one-off commands that can be run against an app. paths: /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/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' components: schemas: 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. ' 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 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. ' 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' 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. ' 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. ' responses: Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Errors' NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Errors' UnprocessableEntity: description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Errors' BadGateway: description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Errors' text/html: schema: type: string Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Errors' Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/Errors' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Errors' ServiceUnavailable: description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/Errors' parameters: 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 Guid: name: guid in: path required: true schema: type: string format: uuid description: The unique identifier for the resource 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 Page: name: page in: query required: false schema: type: integer description: Page to display; valid values are integers >= 1 example: 1 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 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' requestBodies: 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 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