NAV Navbar

Introduction

Overview

Welcome to the Cloud Foundry V3 API docs! Version 3 will add support for several key features:

Getting help

The CAPI team can most easily be reached from 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 the team will be most responsive there.

More resources

Concepts

API Resource

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.

Required fields

Example Person Resource
{
  "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
  "created_at": "2016-03-18T23:26:46Z",
  "updated_at": "2016-10-17T20:00:42Z",

  "name": "Bob",

  "links": {
    "self": {
      "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}
Name Type Description
guid uuid The unique identifier for the resource.
created_at datetime The ISO8601 compatible date and time when resource was created.
updated_at datetime The ISO8601 compatible date and time when resource was last updated.
links links object Provide URLs to related resources and actions for the current resource.

Links provide URLs to relationships and actions for a resource. Links are represented as a JSON object and will always contain at least a self link.

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.

Example Link object
{
  "href": "http://example.com/some/endpoint",
  "method": "GET"
}
Name Type Description
href string The absolute URL.
method string An optional field containing the HTTP method to be used when following the URL.

Authentication

The Cloud Foundry V3 API is secured using OAuth 2. Clients are expected to present a valid bearer token via HTTP header: Authorization: bearer <token>

Tokens can be obtained from the Cloud Foundry UAA server. For more information, see the UAA API Documentation

Authorization

Access to resources is determined by combining scopes in the OAuth2 Token with User Roles that are managed by the API. User Roles are currently managed by the V2 API.

OAuth2 scopes

Scope Description
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 only access to all resources except secrets (such as environment variables)
cloud_controller.read This scope provides read access to resources based on user roles
cloud_controller.write This scope provides write access to resources based on user roles

Cloud Foundry user roles

Role Description
Admin Allows a user to manage the platform. OAuth token must contain cloud_controller.admin scope.
Admin Read-Only Allows a user to read all resources on the platform. OAuth token must contain cloud_controller.admin_read_only scope.
Global Auditor Allows a user to read all resources on the platform, excluding sensitive data such as environment variables and service bindings. OAuth token must contain cloud_controller.global_auditor scope.
Org Member Allows a user to be assigned other roles within an Organization and its Spaces
Org Manager Provides Organization management access
Org Auditor Provides read-only access to a Organization for auditing purposes
Org Billing Manager Allows a user to create and manage billing account and payment information
Space Developer Allows developers to create and manage apps and services in a Space
Space Manager Provides Space management access
Space Auditor Provides read-only access to a Space for auditing purposes

Errors

Example Error
{
  "errors": [
    {
      "code": 10008,
      "title": "CF-UnprocessableEntity",
      "detail": "something went wrong"
    }
  ]
}

An error response will always return a list of error objects in the errors field.

The error object

Name Type Description
code integer A numeric code for this error.
title string Short description of the error.
detail string Detailed description of the error.

Filters

Endpoints that return lists of resources support filtering down the returned resources using query parameters.

Examples

Single value request

GET /v3/apps?names=the_name

This will return all apps with name the_name.

Multiple value request

GET /v3/apps?names=first_name,second_name

This will return all apps with name the_name OR second_name.

Combined filters

GET /v3/apps?names=the_name&state=STARTED

This will return all apps with name the_name AND state STARTED.

Empty filters

An empty filter (/v3/resources?fields=) can mean either empty string ("") or NULL, depending on the resource type.

GET /v3/buildpacks?stacks=

This will return all buildpacks with stack NULL.

GET /v3/routes?paths=pepper,,tabi

This will return all routes with path "pepper", "" OR "tabi".

Include

The include parameter allows clients to fetch resources and ensure that information about the parent object(s) is part of the response. For example, a response to /v3/spaces/:guid?include=org will contain detailed information about the space and its parent org.

Developers may choose to use the include feature to reduce the number of API calls. The include query param can be used with a single resource or a list of resources.

Resources

The following resources can take an include parameter:

Resource Allowed values
apps org, space
apps/[:guid] org, space
spaces org
spaces/[:guid] org

Sample requests

Example request to apps resource to include parent orgs and spaces
curl "https://api.example.org/v3/apps?include=org,space" \
  -X GET \
  -H "Authorization: bearer [token]"
Example response
{
   "pagination": {
      "total_results": 2
      // rest of pagination omitted
   },
   "resources": [
      {
         "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170",
         "name": "app1"
         // rest omitted
      },
      {
         "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
         "name": "app2"
         // rest omitted
      }
   ],
   "included": {
      "spaces": [
         {
            "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
            "name": "space1"
            // rest of info on space1 omitted
         },
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space2"
            // rest of info on space2 omitted
         }
      ],
      "organizations": [
         {
            "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
            "name": "org1"
            // rest of info on org1 omitted
         },
         {
            "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
            "name": "org2"
            // rest of info on org2 omitted
         }
      ]
   }
}
Example request for a single app instance to include its parent space
curl "https://api.example.org/v3/apps/[guid]?include=space" \
  -X GET \
  -H "Authorization: bearer [token]"
Example response
{
   "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837",
   "name": "staticfile",
   // ...
   "included": {
      "spaces": [
         {
            "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
            "name": "space1a"
           // ...
         }
      ]
   }
}
Example request for all spaces including their parent orgs
curl "https://api.example.org/v3/spaces?include=org" \
  -X GET \
  -H "Authorization: bearer [token]"
    Example Response
{
   "pagination": {
      "total_results": 4,
      "total_pages": 1,
     // ...
   },
   "resources": [
      {
         "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b",
         "name": "space"
         // ...
      },
      {
         "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9",
         "name": "space1a"
        // ...
      },
      {
         "guid": "615e724a-dfae-4846-836b-8c413f6192cd",
         "name": "space1b"
         // ...
      },
      {
         "guid": "5801b8dd-5ca6-41bb-ba23-690e703c631a",
         "name": "space2a"
        // ...
      }
   ],
   "included": {
      "organizations": [
         {
            "guid": "b2075a71-28b6-411a-a896-56f75d892f58",
            "name": "org"
            // ...
         },
         {
            "guid": "b56fbd01-296b-442b-8faf-a559aebf985e",
            "name": "org1"
            // ...
         },
         {
            "guid": "c4bf7e09-57e7-453c-8b8e-fbebc986201e",
            "name": "org2"
            // ...
         }
      ]
   }
}

Lifecycles

Lifecycles inform the platform of how to build droplets and run apps. For example the buildpack lifecycle will use a droplet and a rootfs to run the app, while a docker lifecycle will pull a Docker image from a registry to run an app.

The lifecycle object

Name Type Description
type string Type of the lifecycle. Valid values are buildpack, docker.
data object Data that is used during staging and running for a lifecycle.

Buildpack lifecycle

Example Buildpack Lifecycle
{
  "type": "buildpack",
  "data": {
    "buildpacks": ["java_buildpack"],
    "stack": "cflinuxfs3"
  }
}

This is the default lifecycle for Cloud Foundry. When staging an app with this lifecycle, the app source code will be compiled using a buildpack, resulting in a droplet. When running an app with this lifecycle, a container running a rootfs will be created and the droplet will be expanded inside that container to be executed.

Buildpack lifecycle object

Name Type Description
type string buildpack
data.buildpacks array of strings A list of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack.
data.stack string The root filesystem to use with the buildpack, for example cflinuxfs3

Docker lifecycle

Example Docker Lifecycle
{
  "type": "docker",
  "data": {}
}

This allows Cloud Foundry to run Docker images. When staging an app with this lifecycle, the Docker registry is queried for metadata about the image, such as ports and start command. When running an app with this lifecycle, a container is created and the Docker image is executed inside of it.

Docker lifecycle object

Name Type Description
type string docker
data object Data is not used by the Docker lifecycle. Valid value is {}.

Metadata

Metadata allows you to tag API Resources with information that does not directly affect its functionality.

Annotations

Example Resource with Annotations
{
  "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
  "created_at": "2016-03-18T23:26:46Z",
  "updated_at": "2016-10-17T20:00:42Z",

  "name": "api-server",

  "metadata": {
    "labels": {},
    "annotations": {
      "contacts": "Bill tel(1111111) email(bill@fixme), Bob tel(222222) pager(3333333#555) email(bob@fixme)"
    }
  },

  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}

Annotations are user-specified key/value pairs that are attached to API Resources. Annotations are not queryable, non-identifying attributes of a resource, and they do not affect the operation of CloudFoundry.

Examples may include (but are not limited to):

Annotation key

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.

A annotation key prefix must adhere to the following restrictions:

A annotation key name must adhere to the following restrictions:

Annotation value

Annotation values must adhere to the following restrictions:

Labels and selectors

Example Resource with Labels
{
  "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
  "created_at": "2016-03-18T23:26:46Z",
  "updated_at": "2016-10-17T20:00:42Z",

  "name": "api-server",

  "metadata": {
    "labels": {
      "environment": "production",
      "internet-facing": "false"
    },
    "annotations": {}
  },

  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
    }
  }
}

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

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

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:

A label key name must adhere to the following restrictions:

Label values

Label values must adhere to the following restrictions:

Selectors

Example label selector
cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list.

eg: env=dev,!chargeback-code,tier in (backend,worker)

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)

See the metadata documentation for more information.

Updating labels and annotations

Example Initial Metadata
{
  "metadata": {
    "labels": {
      "environment": "staging",
      "ready-to-deploy": "true"
    },
    "annotations": {
       "spring-version": "5.1",
       "app-version": "0.1-alpha"
     }
  }
}
Example Patch Request Body
{
  "metadata": {
    "labels": {
      "environment": "production",
      "ready-to-deploy": null
    },
    "annotations": {
       "app-version": "0.1",
       "deployed-month": "november"
     }
  }
}
Example Final Metadata
{
  "metadata": {
    "labels": {
      "environment": "production"
    },
    "annotations": {
       "spring-version": "5.1",
       "app-version": "0.1",
       "deployed-month": "november"
     }
  }
}

Labels and annotations can be updated by using the PATCH endpoint for their resource. For example, to update labels or annotations on an app, use the update an app endpoint. When patching metadata, CAPI endpoints do a deep merge, only updating labels or annotations that are specified in the request.

Labels and annotations follow the same rules for patching and must be wrapped in the metadata object inside the request body

Pagination

Example Paginated Response
{
  "pagination": {
    "total_results": 3,
    "total_pages": 3,
    "first": {
      "href": "https://api.example.org/v3/people?page=1&per_page=1"
    },
    "last": {
      "href": "https://api.example.org/v3/people?page=3&per_page=1"
    },
    "next": {
      "href": "https://api.example.org/v3/people?page=2&per_page=1"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
      "created_at": "2016-03-18T23:26:46Z",
      "updated_at": "2016-10-17T20:00:42Z",

      "name": "Bob",

      "links": {
        "self": {
          "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2"
        }
      }
    }
  ]
}

Any request that can return multiple resources will be paginated and contain a pagination object and list of resources. Requests for multiple resources can use page, per_page, and order_by in addition to filters specific to the endpoint.

The pagination object

Name Type Description
total_results integer Total number of resources for all pages.
total_pages integer Total number of pages.
first link object Link to the first page.
last link object Link to the last page.
next link object Link to the next page.
previous link object Link to the previous page.

Procfiles

Example Ruby Procfile
web: bundle exec rackup config.ru -p $PORT
rake: bundle exec rake
worker: bundle exec rake workers:start

A Procfile enables you to declare required runtime processes, called process types, for your app. Procfiles must be named Procfile exactly, and placed in the root directory of your application.

In a Procfile, you declare one process type per line and use the syntax PROCESS_TYPE: COMMAND.

Procfile use cases

Many buildpacks provide their own process types and commands by default; however, there are special cases where specifying a custom COMMAND is necessary. Commands can be overwritten by providing a Procfile with the same process type.

For example, a buildpack may provide a worker process type that runs the rake default:start command. If a Procfile is provided that also contains a worker process type, but a different command such as rake custom:start, the rake custom:start command will be used.

Some buildpacks, such as Python, that work on a variety of frameworks, do not attempt to provide a default start command. For these cases, a Procfile should be used to specify any necessary commands for the app.

Web process

web is a special process type that is required for all applications. The web PROCESS_TYPE must be specified by either the buildpack or the Procfile.

Relationships

Relationships represent associations between resources. They can be used to create, read, update, and delete these associations.

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.

Not all resources implement every relationship operation listed below. See the docs for each resource to see how it interacts with its relationships.

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.

Name Type Description
guid string The unique identifier for the related resource.

To-one relationships

Example to-one relationship
{
  "data": {
    "guid": "[related-resource-guid]"
  }
}

Some relationships relate a resource to exactly one other resource. For example an app can belong to only one space.

To-one relationship object

Name Type Description
data relationship object A single relationship
Setting the to-one relationship while creating an object
curl "https://api.example.org/v3/books" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "color": "yellow",
    "relationships": {
      "publisher": {
        "data": {
          "guid": "publisher-guid"
        }
      }
    }
  }'
Modifying the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": {
      "guid": "publisher-guid"
    }
  }'
Removing the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "data": null }'
Viewing the to-one relationship
curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \
  -X GET \
  -H "Authorization: bearer [token]"

To-many relationships

Example to-many relationship
{
  "data": [
    { "guid": "[related-resource-guid-1]" },
    { "guid": "[related-resource-guid-2]" }
  ]
}

Some relationships relate an resource to several other resources. For example an Isolation Segment can be entitled to multiple organizations.

To-many relationship object

Name Type Description
data array of relationship objects An array of multiple relationships.
Adding related to-many resources
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"author-guid-1" },
      { "guid":"author-guid-2" }
    ]
  }'
Replacing all to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"author-guid-3" },
      { "guid":"author-guid-4" }
    ]
  }'
Removing all to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "data": [] }'
Removing specific to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors/[author-guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Viewing the to-many relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors" \
  -X GET \
  -H "Authorization: bearer [token]"

Status Codes

Cloud Foundry V3 API uses a subset of HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that can potentially be fixed by correcting the request, and codes in the 5xx range indicate an error on the server side.

HTTP Status Code Description
200 OK The request completed successfully.
201 Created The request completed successfully and created a new resource.
202 Accepted The request will be completed asynchronously.
204 No Content The request completed successfully and did not return a body.
400 Bad Request The request has malformed or invalid data.
401 Unauthenticated The request requires an authenticated user.
403 Forbidden The request cannot be performed by the user.
404 Not Found The requested resource does not exist.
422 Unprocessable Entity The request cannot be performed.
500 Internal Server Error An unexpected error occurred.
502 Bad Gateway An upstream service caused the request to fail.

Workflows

Many users will think of interactions with Cloud Foundry in terms of a single operation like cf push in order to upload an application to the platform, have it compiled, and schedule it to be run. Performing a push operation actually requires a client to orchestrate several requests to the API to accomplish the entire operation. This section is meant to explain how clients can perform complex workflows using the API.

Push V2 app and run a V3 task

As of CF-245, a V2 application is also available as a V3 application, allowing a user to run a V3 task against it.

  1. Push an application: cf push v3-tasks-sample
  2. Construct a task creation curl: cf curl /v3/apps/$(cf app v3-tasks-sample --guid)/tasks -X POST -d '{"command":"echo foo; sleep 5; echo bar;"}'
  3. Get logs from task: cf logs v3-tasks-sample --recent
  4. Check task state: cf curl /v3/apps/$(cf app v3-tasks-sample --guid)/tasks

For more information, see Create a task.

Resources

Apps

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

The app object

Example App object
{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "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": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name Type Description
name string Name of the app.
state string Current desired state of the app. Valid values are STOPPED or STARTED.
lifecycle lifecycle object Provides the lifecycle object for the application.
guid uuid Unique identifier for the app.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
relationships.space (experimental) to-one relationship The space the app is contained in.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the app.
metadata.annotations (experimental) annotation object Annotations added to the app.

Create an app

Example Request
curl "https://api.example.org/v3/apps" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_app",
    "relationships": {
      "space": {
        "data": {
          "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "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": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/apps

Required parameters

Name Type Description
name string Name of the app.
relationships.space to-one relationship A relationship to a space.

Optional parameters

Name Type Description Default
environment_variables object Environment variables to be used for the App when running. {}
lifecycle lifecycle object Provides the lifecycle object for the application. buildpack lifecycle
metadata.labels (experimental) label object Labels applied to the app.
metadata.annotations (experimental) annotation object Annotations applied to the app.

Permitted roles

Admin
Space Developer

Get an app

Example Request
curl "https://api.example.org/v3/apps/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "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": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

GET /v3/apps/:guid

Query parameters

Name Type Description
include string Experimental - Optionally include additional related resources in the response.
Valid values are space, org or space,org

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List apps

Example Request
curl "https://api.example.org/v3/apps" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/apps?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/apps?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/apps?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
        "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": "cflinuxfs3"
          }
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
            }
          }
        },
        "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"
          }
        },
        "metadata": {
          "labels": {},
          "annotations": {}
        }
      },
      {
        "guid": "02b4ec9b-94c7-4468-9c23-4e906191a0f8",
        "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": "cflinuxfs3"
          }
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
            }
          }
        },
        "links": {
          "self": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
          },
          "space": {
            "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
          },
          "processes": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes"
          },
          "packages": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages"
          },
          "environment_variables": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables"
          },
          "current_droplet": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current"
          },
          "droplets": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets"
          },
          "tasks": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks"
          },
          "start": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start",
            "method": "POST"
          },
          "stop": {
            "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop",
            "method": "POST"
          },
          "revisions": {
            "href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions"
          },
          "deployed_revisions": {
            "href": "https://api.example.org//v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed"
          }
        },
        "metadata": {
          "labels": {},
          "annotations": {}
        }
      }
    ]
  }

Retrieve all apps the user has access to.

Definition

GET /v3/apps

Query parameters

Name Type Description
guids list of strings Comma-delimited list of app guids to filter by.
names list of strings Comma-delimited list of app names to filter by.
space_guids list of strings Comma-delimited list of space guids to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
stacks list of strings Comma-delimited list of stack names to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at, name.
label_selector string Experimental - A query string containing a list of label selector requirements.
include string Experimental - Optionally include a list of unique related resources in the response.
Valid values are space and org, and are separated by a ,
lifecycle_type string Lifecycle type to filter by. Valid values are buildpack, docker.

Permitted roles

All Roles

Update an app

Example Request
curl "https://api.example.org/v3/apps/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_app",
    "lifecycle": {
      "type": "buildpack",
      "data": {
        "buildpacks": ["java_buildpack"]
      }
    }
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "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": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

PATCH /v3/apps/:guid

Optional parameters

Name Type Description
name string Name of the app.
lifecycle lifecycle object Lifecycle to be used when updating the app. Note: data is a required field in lifecycle if lifecycle is updated.
metadata.labels (experimental) label object Labels applied to the app.
metadata.annotations (experimental) annotation object Annotations applied to the app.

Permitted roles

Admin
Space Developer

Delete an app

Example Request
curl "https://api.example.org/v3/apps/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/apps/:guid

Permitted roles

Admin
Space Developer

Get current droplet

Example Request
curl "https://api.example.org/v3/apps/[guid]/droplets/current" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "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": "cflinuxfs3",
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

GET /v3/apps/:guid/droplets/current

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Get current droplet association for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/relationships/current_droplet" \
  -X GET \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
  },
  "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"
    }
  }
}

This endpoint retrieves the current droplet relationship for an app.

Definition

GET /v3/apps/:guid/relationships/current_droplet

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Get environment for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/env" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "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",
          "label": "mysql",
          "tags": ["relational", "sql"],
          "plan": "xlarge",
          "credentials": {
            "username": "user",
            "password": "top-secret"
           },
          "syslog_drain_url": "https://syslog.example.org/drain",
          "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
    }
  }
}

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.

Definition

GET /v3/apps/:guid/env

Permitted roles

Admin
Admin Read-Only
Space Developer

Get environment variables for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/environment_variables" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "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]"
    }
  }
}

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.

Definition

GET /v3/apps/:guid/environment_variables

Permitted roles

Admin
Admin Read-Only
Space Developer

Set current droplet

Example Request
curl "https://api.example.org/v3/apps/[guid]/relationships/current_droplet" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "data": { "guid": "[droplet_guid]" } }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
  },
  "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"
    }
  }
}

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

Definition

PATCH /v3/apps/:guid/relationships/current_droplet

Permitted roles

Admin
Space Developer

Start an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/actions/start" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "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": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/apps/:guid/actions/start

Permitted roles

Admin
Space Developer

Stop an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/actions/stop" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "state": "STOPPED",
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-03-18T11:32:30Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/apps/:guid/actions/stop

Permitted roles

Admin
Space Developer

Update environment variables for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/environment_variables" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: bearer [token]" \
  -d '{
     "var": {
       "DEBUG": "false"
     }
   }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "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]"
    }
  }
}

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.

Definition

PATCH /v3/apps/:guid/environment_variables

Permitted roles

Admin
Space Developer

Builds

Builds represent the process of staging an application package. There are two types (lifecycles) of builds: buildpack and docker.

After an application is created and packages are uploaded, a build resource can be created to initiate the staging process. A successful build results in a droplet.

The build object

Example Build object
{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs3"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": {
    "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
    "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
  },
  "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"
    }
  }
}

Name Type Description
state string State of the build. Valid states are STAGING, STAGED, or FAILED.
error string A string describing errors during the build process.
lifecycle lifecycle object An object describing the lifecycle that was configured or discovered from the app.
package object The package that is the input to the staging process.
droplet object A resulting droplet from the staging process.
guid uuid Unique identifier for the build.
created_at datetime The time with zone when the build was created.
updated_at datetime The time with zone when the build was last updated.
created_by object The user that created the build.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the build.
metadata.annotations (experimental) annotation object Annotations applied to the build.

Create a build

Example Request
curl "https://api.example.org/v3/builds" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "package": {
       "guid": "[package-guid]"
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGING",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs3"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": null,
  "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"
    }
  }
}

Definition

POST /v3/builds

Required parameters

Name Type Description
package object App package to stage.

Optional parameters

Name Type Description Default
lifecycle lifecycle object Lifecycle information for a build. lifecycle on the app
metadata.labels (experimental) label object Labels applied to the build.
metadata.annotations (experimental) annotation object Annotations applied to the build.

Permitted roles

Admin
Space Developer

Get a build

Example Request
curl "https://api.example.org/v3/builds/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs3"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": {
    "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
    "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
  },
  "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"
    }
  }
}

Definition

GET /v3/builds/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List builds

Example Request
curl "https://api.example.org/v3/builds" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "created_by": {
        "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
        "name": "bill",
        "email": "[email protected]"
      },
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": "cflinuxfs3"
        }
      },
      "package": {
        "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
      },
      "droplet": null,
      "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"
        }
      }
    }
  ]
}

Retrieve all builds the user has access to.

Definition

GET /v3/builds

Query parameters

Name Type Description
states list of strings Comma-delimited list of build states to filter by.
app_guids list of strings Comma-delimited list of app guids to filter by.
package_guids list of strings Comma-delimited list of package guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List builds for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/builds" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/apps/[guid]/builds?states=STAGING&page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/[guid]/builds?states=STAGING&page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "created_by": {
        "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
        "name": "bill",
        "email": "[email protected]"
      },
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": "cflinuxfs3"
        }
      },
      "package": {
        "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
      },
      "droplet": null,
      "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"
        }
      }
    }
  ]
}

Retrieve all builds for the app.

Definition

GET /v3/apps/:guid/builds

Query parameters

Name Type Description
states list of strings Comma-delimited list of build states to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a build

Example Request
curl "https://api.example.org/v3/builds/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "created_by": {
    "guid": "3cb4e243-bed4-49d5-8739-f8b45abdec1c",
    "name": "bill",
    "email": "[email protected]"
  },
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs3"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": {
    "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a",
    "href": "https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
  },
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "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"
    }
  }
}

Definition

PATCH /v3/builds/:guid

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the build.
metadata.annotations (experimental) annotation object Annotations applied to the build.

Permitted roles

Admin
Space Developer

Buildpacks

Buildpacks are used during a build to download external dependencies and transform a package into an executable droplet. In this way, buildpacks are a pluggable extension to Cloud Foundry that enable CF to run different languages and frameworks. Buildpacks will automatically detect if they support an application. Buildpacks can also be explicitly specified on apps and builds.

The buildpack object

Example Buildpack object
  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "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"
      }
    }
  }

Name Type Description
guid uuid Unique identifier for the buildpack.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
name string The name of the buildpack. To be used by app buildpack field. (only alphanumeric characters)
state string The state of the buildpack. Valid value is: AWAITING_UPLOAD
filename string The filename of the buildpack.
stack string The name of the stack that the buildpack will use.
position integer The order in which the buildpacks are checked during buildpack auto-detection.
enabled boolean Whether or not the buildpack can be used for staging
locked boolean Whether or not the buildpack is locked to prevent updating the bits
links links object Links to related resources.

Create a buildpack

Example Request
curl "https://api.example.org/v3/buildpacks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "ruby_buildpack",
    "position": 42,
    "enabled": true,
    "locked": false,
    "stack": "windows64"
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "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"
      }
    }
  }

Definition

POST /v3/buildpacks

Required parameters

Name Type Description
name string Name of the buildpack.

Optional parameters

Name Type Description Default
stack string The name of the stack that the buildpack will use. null
position integer The order in which the buildpacks are checked during buildpack auto-detection. 1
enabled boolean Whether or not the buildpack will be used for staging true
locked boolean Whether or not the buildpack is locked to prevent updating the bits false
metadata.labels (experimental) label object Labels applied to the buildpack.
metadata.annotations (experimental) annotation object Annotations applied to the buildpack.

Permitted roles

Admin

Get a buildpack

Example Request
curl "https://api.example.org/v3/buildpacks/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "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"
      }
    }
  }

Definition

GET /v3/buildpacks/:guid

Permitted roles

All Roles

List buildpacks

Example Request
curl "https://api.example.org/v3/buildpacks" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "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": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
        "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,
        "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"
          }
        }
      }
    ]
  }

Retrieve all buildpacks the user has access to.

Definition

GET /v3/buildpacks

Query parameters

Name Type Description
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
names list of strings Comma-delimited list of buildpack names to filter by.
stacks list of strings Comma-delimited list of stack names to filter by.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at, and position.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

Update a buildpack

Example Request
curl "https://api.example.org/v3/buildpacks/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "ruby_buildpack",
    "position": 42,
    "enabled": true,
    "locked": false,
    "stack": "windows64"
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "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"
      }
    }
  }

Definition

PATCH /v3/buildpacks/:guid

Optional parameters

Name Type Description
name string Name of the buildpack.
stack string The name of the stack that the buildpack will use.
position integer The order in which the buildpacks are checked during buildpack auto-detection.
enabled boolean Whether or not the buildpack will be used for staging
locked boolean Whether or not the buildpack is locked to prevent updating the bits
metadata.labels (experimental) label object Labels applied to the buildpack.
metadata.annotations (experimental) annotation object Annotations applied to the buildpack.

Permitted roles

Admin

Delete a buildpack

Example Request
curl "https://api.example.org/v3/buildpacks/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/buildpacks/:guid

Permitted Roles

Admin

Upload buildpack bits

Example Request
curl "https://api.example.org/v3/buildpacks/[guid]/upload" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -F bits=@"buildpack.zip"
Example Response
HTTP/1.1 202 OK
Content-Type: application/json
Location: https://api.example.org/v3/jobs/[guid]

  {
    "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2",
    "created_at": "2016-03-18T23:26:46Z",
    "updated_at": "2016-10-17T20:00:42Z",
    "name": "ruby_buildpack",
    "state": "AWAITING_UPLOAD",
    "filename": null,
    "stack": "windows64",
    "position": 42,
    "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"
      }
    }
  }

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

Definition

POST /v3/buildpacks/:guid/upload

Required parameters

Name Type Description
bits form field A binary zip file containing the buildpack bits.

Permitted roles

Admin

Domains

Domains represent 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.

The domain object

Example Domain object
  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Name Type Description
guid uuid Unique identifier for the domain.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
name string The name of the domain.
Must be between 3 ~ 253 characters and follow RFC 1035.
internal boolean Whether the domain is used for internal (container-to-container) traffic.
organization to-one relationship The organization the domain is scoped to. If set, the domain will only be available in that organization. Otherwise, the domain will be globally available.
shared_organizations to-many relationship Organizations the domain is shared with. If set, the domain will be available in these organizations in addition to the organization the domain is scoped to.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the domain.
metadata.annotations (experimental) annotation object Annotations applied to the domain.

Create a domain

Example Request
curl "https://api.example.org/v3/domains" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "example.com",
    "internal": false
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Definition

POST /v3/domains

Required parameters

Name Type Description
name string Name of the domain.

Optional parameters

Name Type Description Default
internal boolean Whether the domain is used for internal (container-to-container) traffic. false
organization to-one relationship A relationship to the organization the domain will be scoped to.
Note: can not be used with the internal param
shared_organizations to-many relationship A relationship to organizations the domain will be shared with.
Note: can not be used without an organization relationship
metadata.labels (experimental) label object Labels applied to the domain.
metadata.annotations (experimental) annotation object Annotations applied to the domain.

Permitted roles

Role Notes
Admin
Org Manager When an organization relationship is provided.

Get a domain

Example Request
curl "https://api.example.org/v3/domains/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Definition

GET /v3/domains/:guid

Permitted roles

Roles Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor
Org Billing Manager Can only view domains without an organization relationship.
Org Manager
Space Auditor
Space Developer
Space Manager

List domains

Example Request
curl "https://api.example.org/v3/domains" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/domains?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/domains?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/domains?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
        "created_at": "2019-03-08T01:06:19Z",
        "updated_at": "2019-03-08T01:06:19Z",
        "name": "test-domain.com",
        "internal": false,
        "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"
          },
        }
      }
    ]
  }

Retrieve all domains the user has access to.

Definition

GET /v3/domains

Query parameters

Name Type Description
guids list of strings Comma-delimited list of guids to filter by.
names list of strings Comma-delimited list of domain names to filter by.
organization_guids list of strings Comma-delimited list of owning organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List domains for an organization

Example Request
curl "https://api.example.org/v3/organizations/[guid]/domains" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/domains?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/domains?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/domains?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
        "created_at": "2019-03-08T01:06:19Z",
        "updated_at": "2019-03-08T01:06:19Z",
        "name": "test-domain.com",
        "internal": false,
        "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"
          },
        }
      }
    ]
  }

Retrieve all domains available in an organization for the current user. This will return user-visible domains without an organization relationship AND domains scoped or shared with the organization.

Definition

GET /v3/organizations/:guid/domains

Query parameters

Name Type Description
guids list of strings Comma-delimited list of guids to filter by.
names list of strings Comma-delimited list of domain names to filter by.
organization_guids list of strings Comma-delimited list of owning organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

Update a domain

Example Request
curl "https://api.example.org/v3/domains/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "metadata": {
      "labels": {"key": "value"},
      "annotations": {"note": "detailed information"}
    }
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { "key": "value" },
      "annotations": { "note": "detailed information" }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Definition

PATCH /v3/domains/:guid

Optional parameters

Name Type Description Default
metadata.labels (experimental) label object Labels applied to the domain.
metadata.annotations (experimental) annotation object Annotations applied to the domain.

Permitted roles

Role Notes
Admin
Org Manager If domain is scoped to organization managed by the org manager.

Delete a domain

Example Request
curl "https://api.example.org/v3/domains/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/domains/:guid

Permitted roles

Role Notes
Admin
Org Manager If domain is scoped to organization managed by the org manager.

Share a domain

Example Request
curl "https://api.example.org/v3/domains/[guid]/relationships/shared_organizations" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
      {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
    ]
  }'
Example Response
HTTP/1.1 200 Created
Content-Type: application/json

  {
    "data": [
      {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"}
      {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
    ]
  }

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.

Definition

POST /v3/domains/:guid/relationships/shared_organizations

Required parameters

Name Type Description
data to-many relationship The organization guids with which to share the domain.

Permitted roles

Role Notes
Admin
Org Manager

Unshare a domain

Example Request
curl "https://api.example.org/v3/domains/[guid]/relationships/shared_organizations/[org_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json"
Example Response
HTTP/1.1 204 No Content

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.

Definition

DELETE /v3/domains/:guid/relationships/shared_organizations/:org_guid

Permitted roles

Role Notes
Admin
Org Manager Can be in either the domain’s owning organization or the organization it has been shared to

Droplets

Droplets are 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.

After an application is created and packages are uploaded, a droplet must be created via a build in order for an application to be deployed or tasks to be run. The current droplet must be assigned to an application before it may be started. When tasks are created, they either use a specific droplet guid, or use the current droplet assigned to an application.

The droplet object

Example Droplet object
{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "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": "cflinuxfs3",
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name Type Description
state string State of the droplet. Valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, STAGED, COPYING, FAILED, or EXPIRED.
error string A string describing the last error during the droplet lifecycle.
lifecycle lifecycle object An object describing the lifecycle that was configured or discovered from the app. lifecycle.data will always be an empty hash for a droplet object.
guid uuid Unique identifier for the droplet.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.
execution_metadata string Serialized JSON data resulting from staging for use when executing a droplet.
process_types object The process types (keys) and associated start commands (values) that will be created when the droplet is executed.
metadata.labels (experimental) labels object Labels on the droplet
metadata.annotations (experimental) annotations object Annotations on the droplet

In addition to these fields, a droplet object will contain the following fields from both lifecycles. Their values will be null by default and will contain values when the droplet is of a specific lifecycle.type.

Buildpack droplet

Name Type Description
checksum.type string Hashing algorithm for checksum. Supported algorithms are sha256 and sha1.
checksum.value string Checksum of droplet.
buildpacks array of detected buildpack objects Detected buildpacks from the staging process.
stack string The root filesystem to use with the buildpack, for example cflinuxfs3
Detected buildpack object
Name Type Description
name string System buildpack name
detect_output string Output during buildpack detect process
buildpack_name string Name reported by the buildpack
version string Version reported by the buildpack

Docker droplet

Name Type Description
image string Docker image name.

Create a droplet

Example Request
curl "https://api.example.org/v3/droplets" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "relationships": {
      "app": {
        "data": {
          "guid": "[app-guid]"
        }
      }
    },
    "process_types": {
      "rake": "bundle exec rake",
      "web": "bundle exec rackup config.ru -p $PORT"
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "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": "cflinuxfs3",
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "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": {}
  }
}

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

Definition

POST /v3/droplets

Required parameters

Name Type Description
app to-one relationship App to create droplet for.

Optional parameters

Name Type Description Default
process_types hash Process names and start commands for the droplet. {"web": ""}

Permitted roles

Admin
Space Developer

Get a droplet

Example Request
curl "https://api.example.org/v3/droplets/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "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": "cflinuxfs3",
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-03-28T23:39:47Z",
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

GET /v3/droplets/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List droplets

Example Request
curl "https://api.example.org/v3/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {}
      },
      "image": null,
      "execution_metadata": "PRIVATE DATA HIDDEN",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "checksum": {
        "type": "sha256",
        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "buildpacks": [
        {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14",
          "version": "1.1.1.",
          "buildpack_name": "ruby"
        }
      ],
      "stack": "cflinuxfs3",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "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"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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",
      "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": {}
      }
    }
  ]
}

Retrieve all droplets the user has access to.

Definition

GET /v3/droplets

Query parameters

Name Type Description
guids list of strings Comma-delimited list of droplet guids to filter by.
states list of strings Comma-delimited list of droplet states to filter by.
app_guids list of strings Comma-delimited list of app guids to filter by.
space_guids list of strings Comma-delimited list of space guids to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at and updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List droplets for a package

Example Request
curl "https://api.example.org/v3/packages/[guid]/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {}
      },
      "image": null,
      "execution_metadata": "PRIVATE DATA HIDDEN",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "checksum": {
        "type": "sha256",
        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "buildpacks": [
        {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14",
          "version": "1.1.1.",
          "buildpack_name": "ruby"
        }
      ],
      "stack": "cflinuxfs3",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "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"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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",
      "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": {}
      }
    }
  ]
}

Retrieve a list of droplets belonging to a package.

Definition

GET /v3/packages/:guid/droplets

Query parameters

Name Type Description
guids list of strings Comma-delimited list of droplet guids to filter by.
states list of strings Comma-delimited list of droplet states to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at and updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List droplets for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {}
      },
      "image": null,
      "execution_metadata": "PRIVATE DATA HIDDEN",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "checksum": {
        "type": "sha256",
        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "buildpacks": [
        {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14",
          "version": "1.1.1.",
          "buildpack_name": "ruby"
        }
      ],
      "stack": "cflinuxfs3",
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "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"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
      "process_types": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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",
      "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": {}
      }
    }
  ]
}

Retrieve a list of droplets belonging to an app.

Definition

GET /v3/apps/:guid/droplets

Query parameters

Name Type Description
guids list of strings Comma-delimited list of droplet guids to filter by.
states list of strings Comma-delimited list of droplet states to filter by.
current boolean If true, only include the droplet currently assigned to the app.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at and updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a droplet

Example Request
curl "https://api.example.space/v3/droplets/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
    "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": "cflinuxfs3",
    "image": null,
    "created_at": "2016-03-28T23:39:34Z",
    "updated_at": "2016-03-28T23:39:47Z",
    "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"
      }
    },
    "metadata": {
      "labels": {
        "release": "stable"
      },
      "annotations": {
        "note": "detailed information"
      }
    }
  }

Definition

PATCH /v3/droplets/:guid

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the droplet.
metadata.annotations (experimental) annotation object Annotations applied to the droplet.

Permitted roles

Admin
Org Manager
Space Developer
Space Manager

Delete a droplet

Example Request
curl "https://api.example.org/v3/droplets/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/droplets/:guid

Permitted Roles

Admin
Space Developer

Copy a droplet

Example Request
curl "https://api.example.org/v3/droplets?source_guid=[guid]" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "relationships": {
      "app": {
        "data": {
          "guid": "[app-guid]"
        }
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "COPYING",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {}
  },
  "execution_metadata": "",
  "process_types": null,
  "checksum": null,
  "buildpacks": null,
  "stack": null,
  "image": null,
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Copy a droplet to a different app. The copied droplet excludes the environment variables listed on the source droplet.

Definition

POST /v3/droplets?source_guid=:guid

Required query parameters

Name Type Description
source_guid uuid Source guid of the droplet to be copied.

Required parameters

Name Type Description
relationships.app to-one relationship A relationship to the destination app.

Permitted roles

Admin
Space Developer

Upload droplet bits

Example Request
curl "https://api.example.org/v3/droplets/[guid]/upload" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -F bits=@"droplet.tgz"
Example Response
HTTP/1.1 202 OK
Content-Type: application/json
Location: https://api.example.org/v3/jobs/[guid]

{
  "guid": "3c64aba2-2d9e-4eea-9e07-6fec1636315e",
  "state": "PROCESSING_UPLOAD",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {}
  },
  "checksum": null,
  "buildpacks": [],
  "stack": null,
  "image": null,
  "execution_metadata": "",
  "process_types": {
    "rake": "bundle exec rake",
    "web": "bundle exec rackup config.ru -p $PORT"
  },
  "created_at": "2019-05-15T22:43:54Z",
  "updated_at": "2019-05-15T22:53:02Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/3c64aba2-2d9e-4eea-9e07-6fec1636315e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4/relationships/current_droplet",
      "method": "PATCH"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

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

Definition

POST /v3/droplets/:guid/upload

Required parameters

Name Type Description
bits form field A gzip compressed tarball file with .tgz extension containing the droplet bits.

Permitted roles

Admin
Space Developer

Feature Flags

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

The feature flag object

Example Feature Flag object
  {
    "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 Type Description
name string The name of the feature flag.
enabled boolean Whether the feature flag is enabled.
updated_at datetime The time with zone when the object was last updated. This will be blank for feature flags that have not been configured.
custom_error_message string The error string returned by the API when a client performs an action disabled by the feature flag.
links links object Links to related resources.

List of feature flags

Name: app_bits_upload
Default: true
Description: When enabled, space developers can upload app bits. When disabled, only admin users can upload app bits.
Name: app_scaling
Default: true
Description: When enabled, space developers can perform scaling operations (i.e. change memory, disk or instances). When disabled, only admins can perform scaling operations.
Name: diego_docker
Default: false
Description: When enabled, Docker applications are supported by Diego. When disabled, Docker applications will stop running. It will still be possible to stop and delete them and update their configurations.
Name: env_var_visibility
Default: true
Description: When enabled, all users can see their environment variables. When disabled, no users can see environment variables.
Name: hide_marketplace_from_unauthenticated_users
Default: false
Description: When enabled, service offerings available in the marketplace will be hidden from unauthenticated users. When disabled, unauthenticated users will be able to see the service offerings available in the marketplace.
Name: private_domain_creation
Default: true
Description: When enabled, an organization manager can create private domains for that organization. When disabled, only admin users can create private domains.
Name: route_creation
Default: true
Description: When enabled, a space developer can create routes in a space. When disabled, only admin users can create routes.
Name: service_instance_creation
Default: true
Description: When enabled, a space developer can create service instances in a space. When disabled, only admin users can create service instances.
Name: service_instance_sharing
Default: false
Description: When enabled, Space Developers can share service instances between two spaces (even across orgs!) in which they have the Space Developer role. When disabled, Space Developers cannot share service instances between two spaces.
Name: set_roles_by_username
Default: true
Description: When enabled, Org Managers or Space Managers can add access roles by username. In order for this feature to be enabled the CF operator must:
1) Enable the /ids/users/ endpoint for UAA
2) Create a UAA cloud_controller_username_lookup client with the scim.userids authority
Name: space_developer_env_var_visibility
Default: true
Description: When enabled, space developers can do a get on the /v2/apps/:guid/env and /v3/apps/:guid/env end points. When disabled, space developers can no longer do a get against these end points.
Name: space_scoped_private_broker_creation
Default: true
Description: When enabled, space developers can create space scoped private brokers. When disabled, only admin users can create create space scoped private brokers.
Name: task_creation
Default: true
Description: When enabled, space developers can create tasks. When disabled, only admin users can create tasks.
Name: unset_roles_by_username
Default: true
Description: When enabled, Org Managers or Space Managers can remove access roles by username. In order for this feature to be enabled the CF operator must:
1) Enable the /ids/users/ endpoint for UAA
2) Create a UAA cloud_controller_username_lookup client with the scim.userids authority
Name: user_org_creation
Default: false
Description: When enabled, any user can create an organization via the API. When disabled, only admin users can create organizations via the API.

Get a feature flag

Example Request
curl "https://api.example.org/v3/feature_flags/[name]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

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

Definition

GET /v3/feature_flags/:name

Permitted roles

All Roles

List feature flags

Example Request
curl "https://api.example.org/v3/feature_flags" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "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"
          }
        }
      }
    ]
  }

Retrieve all feature_flags.

Definition

GET /v3/feature_flags

Query parameters

Name Type Description
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to name ascending. Prepend with - to sort descending.
Valid value is name.

Permitted roles

All Roles

Update a feature flag

Example Request
curl "https://api.example.org/v3/feature_flags/[name]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "enabled": true,
    "custom_error_message": "error message the user sees"
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

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

Definition

PATCH /v3/feature_flags/:name

Optional parameters

Name Type Description
enabled boolean Whether the feature flag is enabled.
custom_error_message string The error string returned by the API when a client performs an action disabled by the feature flag.

Permitted roles

Admin

Isolation Segments

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

The isolation segment object

Example Isolation Segment object
{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "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": {}
   }
}

Name Type Description
name string Name of the isolation segment.
guid uuid Unique identifier for the isolation segment.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.
metadata.labels (experimental) labels object Labels on the isolation segment
metadata.annotations (experimental) annotations object Annotations on the isolation segment

Create an isolation segment

Example Request
curl "https://api.example.org/v3/isolation_segments" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_segment"
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "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": {}
   }
}

Definition

POST /v3/isolation_segments

Required parameters

Name Type Description
name string Name of the Isolation Segment. Isolation Segment names must be unique across the entire system, and case is ignored when checking for uniqueness.
metadata.labels (experimental) label object Labels applied to the isolation segment.
metadata.annotations (experimental) annotation object Annotations applied to the isolation segment.

Permitted roles

Admin

Get an isolation segment

Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "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": {}
   }
}

Definition

GET /v3/isolation_segments/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List isolation segments

Example Request
curl "https://api.example.org/v3/isolation_segments" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "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": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
         "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": "68d54d31-9b3a-463b-ba94-e8e4c32edbac",
         "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": "ecdc67c3-a71e-43ff-bddf-048930b8cd03",
         "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": "424c89e4-4353-46b7-9bf4-f90bd9bacac0",
         "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": "0a79fcec-a648-4eb8-a6c3-2b5be39047c7",
         "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": {}
         }
      }
   ]
}

Retrieves all isolation segments to which the user has access. For admin, this is all the isolation segments in the system. For an org manager, this is the isolation segments in the allowed list for any organization to which the user belongs. For any other user, this is the isolation segments assigned to any spaces to which the user has access.

Definition

GET /v3/isolation_segments

Query parameters

Name Type Description
guids list of strings Comma-delimited list of isolation segment guids to filter by.
names list of strings Comma-delimited list of isolation segment names to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at, and name.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List organizations relationship

Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ],
  "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"
    }
  }
}

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.

Definition

GET /v3/isolation_segments/:guid/relationships/organizations

Permitted roles

All Roles

List spaces relationship

Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/spaces" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
    }
  }
}

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.

Definition

GET /v3/isolation_segments/:guid/relationships/spaces

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update an isolation segment

Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "name": "my_isolation_segment" }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
   "name": "my_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": {}
   }
}

Definition

PATCH /v3/isolation_segments/:guid

Optional parameters

Name Type Description
name string Name of the Isolation Segment. Isolation Segment names must be unique across the entire system, and case is ignored when checking for uniqueness.
metadata.labels (experimental) label object Labels applied to the isolation segment.
metadata.annotations (experimental) annotation object Annotations applied to the isolation segment.

Permitted roles

Admin

Delete an isolation segment

Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

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

Definition

DELETE /v3/isolation_segments/:guid

Permitted roles

Admin

Entitle organizations for an isolation segment

Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"org-guid-1" },
      { "guid":"org-guid-2" }
    ]
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ],
  "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"
    }
  }
}

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.

Definition

POST /v3/isolation_segments/:guid/relationships/organizations

Required parameters

Name Type Description
data to-many relationship Organization relationships. Each organization will be entitled to manage this isolation segment.

Permitted roles

Admin

Revoke entitlement to isolation segment for an organization

Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations/[org_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

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.

Definition

DELETE /v3/isolation_segments/:guid/relationships/organizations/:org_guid

Permitted roles

Admin

Jobs

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

The job object

Example Job object
{
  "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
  "created_at": "2016-10-19T20:25:04Z",
  "updated_at": "2016-11-08T16:41:26Z",
  "operation": "app.delete",
  "state": "COMPLETE",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
    }
  },
  "errors": []
}

Name Type Description
guid uuid Unique identifier for the job.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
operation string Current desired operation of the job on a model.
state string State of the job. Valid values are PROCESSING, COMPLETE, orFAILED.
links links object Links to related resources.
errors errors list Array of errors that occurred while processing the job.

Get a job

Example Request
curl "https://api.example.org/v3/jobs/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Completed Job Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
  "created_at": "2016-10-19T20:25:04Z",
  "updated_at": "2016-11-08T16:41:26Z",
  "operation": "app.delete",
  "state": "COMPLETE",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c"
    }
  },
  "errors": []
}

Failed Job Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "b19ae525-cbd3-4155-b156-dc0c2a431b4c",
  "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"
    }
  ]
}

Definition

GET /v3/jobs/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Organizations

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.

The organization object

Example Organization object
{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "suspended": false,
  "relationships": {
    "quota": {
      "data": {
        "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name Type Description
guid uuid Unique identifier for the organization.
name string Name of the organization.
suspended boolean Whether an organization is suspended or not. Non-admins will be blocked from creating, updating, or deleting resources in a suspended organization.
relationships.quota (experimental) to-one relationship The quota applied to the organization.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the organization.
metadata.annotations (experimental) annotation object Annotations added to the organization.

Create an organization

Example Request
curl "https://api.example.org/v3/organizations" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-organization" }'

Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "suspended": false,
  "relationships": {
    "quota": {
      "data": {
        "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/organizations

Required parameters

Name Type Description
name string Organization name

Optional parameters

Name Type Description
suspended (experimental) boolean Whether an organization is suspended or not.
metadata.labels (experimental) label object Labels applied to the organization.
metadata.annotations (experimental) annotation object Annotations applied to the organization.

Permitted roles

Admin

If the user_org_creation feature flag is enabled, any user with the cloud_controller.write scope will be able to create organizations.

Get an organization

Example Request
curl "https://api.example.org/v3/organizations/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "suspended": false,
  "relationships": {
    "quota": {
      "data": {
        "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

This endpoint retrieves the specified organization object.

Definition

GET /v3/organizations/:guid

Permitted roles

All Roles

List organizations

Example Request
curl "https://api.example.org/v3/organizations" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "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": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "name": "org1",
      "suspended": false,
      "relationships": {
        "quota": {
          "data": {
            "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
          }
        }
      },
      "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"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
      "created_at": "2017-02-02T00:14:30Z",
      "updated_at": "2017-02-02T00:14:30Z",
      "name": "org2",
      "suspended": false,
      "relationships": {
        "quota": {
          "data": {
            "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
          }
        }
      },
      "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"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve all organizations the user has access to.

Definition

GET /v3/organizations

Query parameters

Name Type Description
names list of strings Comma-delimited list of organization names to filter by.
guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at, and name.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List organizations for isolation segment

Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]/organizations" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "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": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "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"
        }
      },
      "relationships": {
        "quota": {
          "data": {
            "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
      "created_at": "2017-02-02T00:14:30Z",
      "updated_at": "2017-02-02T00:14:30Z",
      "name": "org2",
      "suspended": false,
      "relationships": {
        "quota": {
          "data": {
            "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
          }
        }
      },
      "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"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

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

Definition

GET /v3/isolation_segments/:guid/organizations

Query parameters

Name Type Description
names list of strings Comma-delimited list of organization names to filter by.
guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at, and name.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Auditor
Org Billing Manager
Org Manager

Update an organization

Example Request
curl "https://api.example.org/v3/organizations/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-organization" }'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "24637893-3b77-489d-bb79-8466f0d88b52",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-organization",
  "suspended": false,
  "relationships": {
    "quota": {
      "data": {
        "guid": "b7887f5c-34bb-40c5-9778-577572e4fb2d"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

PATCH /v3/organizations/:guid

Optional parameters

Name Type Description
name string Organization name
suspended (experimental) boolean Whether an organization is suspended or not.
metadata.labels (experimental) label object Labels applied to the organization.
metadata.annotations (experimental) annotation object Annotations applied to the organization.

Permitted roles

Admin
Org Manager

Delete an organization

Example Request
curl "https://api.example.org/v3/organizations/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/organizations/:guid

Permitted roles

Role Notes
Admin

Assign default isolation segment

Example Request
curl "https://api.example.org/v3/organizations/[guid]/relationships/default_isolation_segment" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "guid": "[iso-seg-guid]"
     }
   }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
  },
  "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"
    }
  }
}

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.

Definition

PATCH /v3/organizations/:guid/relationships/default_isolation_segment

Required parameters

Name Type Description
data to-one relationship Isolation segment relationship. Apps will run in this isolation segment. Set data to null to remove the relationship.

Permitted roles

Admin
Org Manager

Get default isolation segment

Example Request
curl "https://api.example.org/v3/organizations/[guid]/relationships/default_isolation_segment" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "9d8e007c-ce52-4ea7-8a57-f2825d2c6b39"
  },
  "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"
    }
  }
}

Retrieve the default isolation segment for a given organization.

Definition

GET /v3/organizations/:guid/relationships/default_isolation_segment

Permitted roles

All Roles

Get default domain

Example Request
curl "https://api.example.org/v3/organizations/[guid]/domains/default" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "name": "test-domain.com",
    "internal": false,
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "organization": {
        "data": { "guid": "3a3f3d89-3f89-4f05-8188-751b298c79d5" }
      },
      "shared_organizations": {
        "data": [
          {"guid": "404f3d89-3f89-6z72-8188-751b298d88d5"},
          {"guid": "416d3d89-3f89-8h67-2189-123b298d3592"}
        ]
      }
    },
    "links": {
      "self": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      },
      "organization": {
        "href": "https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5"
      },
      "route_reservations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations"
      },
      "shared_organizations": {
        "href": "https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations"
      }
    }
  }

Retrieve the default domain for a given organization.

Definition

GET /v3/organizations/:guid/domains/default

Permitted roles

Roles Notes
Space Developer
Space Manager
Space Auditor
Org Auditor
Org Manager
Org Billing Manager Can only view domains without an organization relationship.
Admin
Admin Read-Only
Global Auditor

Get usage summary

Example Request
curl "https://api.example.org/v3/organizations/[guid]/usage_summary" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "usage_summary": {
    "started_instances": 3,
    "memory_in_mb": 50
  },
  "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"
    }
  }
}

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

Definition

GET /v3/organizations/:guid/usage_summary

Permitted roles

All Roles

Packages

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

In Cloud Foundry, packages are staged to produce an executable Droplet. We currently support raw bits and Docker packages.

The package object

Example Package object
{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

Name Type Description
type string Package type. Valid values are bits, docker.
data object Data for package type.
state string State of the package. Valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, EXPIRED.
guid uuid Unique identifier for the package.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the package.
metadata.annotations (experimental) annotation object Annotations applied to the package.

Bits package

A bits package is used to upload source code for an app to. The bits package will provide an upload link to which a zip file should be uploaded.

Name Type Description
type string bits
data.error string If an error occurs this field will contain the error message.
data.checksum.type string The checksum type, for example: sha256.
data.checksum.value string The checksum value. This will be populated after bits are uploaded.
state string State of the package. Valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, EXPIRED.
guid uuid Unique identifier for the package.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the package.
metadata.annotations (experimental) annotation object Annotations applied to the package.

Docker package

A Docker package references a Docker image from a registry.

Name Type Description
type string docker
data.image string The registry address of the image.
data.username string The username for the image’s registry.
data.password string The password for the image’s registry.
state string State of the package. Valid states are READY, FAILED, COPYING, EXPIRED.
guid uuid Unique identifier for the package.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the package.
metadata.annotations (experimental) annotation object Annotations applied to the package.

Create a package

Example Request (buildpack app)
curl "https://api.example.org/v3/packages" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "bits",
    "relationships": {
      "app": {
        "data": {
          "guid": "[guid]"
        }
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "AWAITING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

Example Request (Docker app)
curl "https://api.example.org/v3/packages" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "docker",
    "relationships": {
      "app": {
        "data": {
          "guid": "[guid]"
        }
      }
    },
    "data": {
      "image": "registry/image:latest",
      "username": "username",
      "password": "password"
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "4cb65058-f04f-458f-aca1-5f4e43de6407",
  "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",
  "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": {}
  }
}

Definition

POST /v3/packages

Required parameters

Name Type Description
type string Type of the package. Valid values are bits, docker.
relationships.app to-one relationship A relationship to an app.

Optional parameters

Name Type Description Default
data object Data for package type. {}

Conditional Parameters

Name Type Description
data.image string Required when type is docker. The registry address of the image.
data.username string Optional when type is docker and accessing a secured registry.
data.password string Optional when type is docker and accessing a secured registry.
metadata.labels (experimental) label object Labels applied to the package.
metadata.annotations (experimental) annotation object Annotations applied to the package.

Permitted roles

Admin
Space Developer

Get a package

Example Request
curl "https://api.example.org/v3/packages/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

Definition

GET /v3/packages/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List packages

Example Request
curl "https://api.example.org/v3/packages" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "a57fd932-85db-483a-a27e-b00efbb3b0a4",
      "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",
      "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": "8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691",
      "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",
      "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": {}
      }
    }
  ]
}

Retrieve all packages the user has access to.

Definition

GET /v3/packages

Query parameters

Name Type Description
guids list of strings Comma-delimited list of package guids to filter by.
states list of strings Comma-delimited list of package states to filter by.
types list of strings Comma-delimited list of package types to filter by.
app_guids list of strings Comma-delimited list of app guids to filter by.
space_guids list of strings Comma-delimited list of space guids to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List packages for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/packages" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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": "752edab0-2147-4f58-9c25-cd72ad8c3561",
      "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",
      "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": {}
      }
    }
  ]
}

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

Definition

GET /v3/apps/:guid/packages

Query parameters

Name Type Description
guids list of strings Comma-delimited list of package guids to filter by.
states list of strings Comma-delimited list of package states to filter by.
types list of strings Comma-delimited list of package types to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a package

Example Request
curl "https://api.example.org/v3/packages/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

Definition

PATCH /v3/packages/:guid

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the package.
metadata.annotations (experimental) annotation object Annotations applied to the package.

Permitted roles

Admin
Space Developer

Delete a package

Example Request
curl "https://api.example.org/v3/packages/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/packages/:guid

Permitted Roles

Admin
Space Developer

Copy a package

Example Request
curl "https://api.example.org/v3/packages?source_guid=[guid]" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "relationships": {
      "app": {
        "data": {
          "guid": "[destination-app-guid]"
        }
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "fec72fc1-e453-4463-a86d-5df426f337a3",
  "type": "docker",
  "data": {
    "image": "http://awesome-sauce.example.org"
  },
  "state": "COPYING",
  "created_at": "2016-03-17T21:41:09Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/36208a68-562d-4f51-94ea-28bd8553a271"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

This endpoint copies the bits of a source package to a target package.

Definition

POST /v3/packages?source_guid=:guid

Required query parameters

Name Type Description
source_guid uuid GUID of the source package to copy from.

Required parameters

Name Type Description
relationships.app to-one relationship A relationship to the destination app.

Permitted roles

Admin
Space Developer

Download package bits

Example Request
curl "https://api.example.org/v3/packages/[guid]/download" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 302 Found

You are being redirected.

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.

Definition

GET /v3/packages/:guid/download

Permitted roles

Admin
Space Developer

Stage a package

Staging a package is accomplished by creating a build. See Create a build.

Upload package bits

Example Request
curl "https://api.example.org/v3/packages/[guid]/upload" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -F bits=@"package.zip" \
  -F resources='[{"path":"path/to/content.txt","size_in_bytes":123,"checksum": {"value": "b907173290db6a155949ab4dc9b2d019dea0c901"}},{"path":"path/to/code.jar","size_in_bytes":123,"checksum": {"value": "ff84f89760317996b9dd180ab996b079f418396f"}},{"path":"path/to/code.jar","size_in_bytes":123,"checksum": {"value": "ff84f89760317996b9dd180ab996b079f418396f"},"mode":"644"}]'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "checksum": {
      "type": "sha256",
      "value": null
    },
    "error": null
  },
  "state": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

This upload endpoint takes a multi-part form requests for packages of type bits. The request requires either a .zip file uploaded under the bits field or a list of resource match objects under the resources field. These field may be used together.

The resources field in the request accepts the v2 resources object format.

Definition

POST /v3/packages/:guid/upload

Optional parameters

Name Type Description Default
bits form field A binary zip file containing the package bits.
resources form field Fingerprints of the application bits that have previously been pushed to Cloud Foundry, formatted as resource match objects. []

Permitted roles

Admin
Space Developer

Processes

Processes define the runnable units of an app. An app can have multiple process types, each with differing commands and scale. Processes for an app are defined by the buildpack used to stage the app and can be customized by including a Procfile in the application source.

Web process type

The process object

Example Process object
{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "relationships": {
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "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"
    }
  }
}

Name Type Description
type string Process type. A unique identifier for processes belonging to an app.
command string or null The command used to start the process. Use null to revert to the buildpack-detected or procfile-provided start command.
instances integer The number of instances to run.
memory_in_mb integer The memory in MB allocated per instance.
disk_in_mb integer The disk in MB allocated per instance.
health_check health check object The health check to perform on the process.
relationships.revision (experimental) to-one relationship The app revision the process is currently running.
guid uuid Unique identifier for the process.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the process.
metadata.annotations (experimental) annotation object Annotations applied to the process.

The health check object

Example health check object
{
  "type": "port",
  "data": {
    "timeout": null
  }
}

Name Type Description
type string The type of health check to perform. Valid values are http, port, and process. Default is port.
data.timeout integer The duration in seconds that health checks can fail before the process is restarted.
data.invocation_timeout integer The timeout in seconds for individual health check requests for http and port health checks.
data.endpoint string The endpoint called to determine if the app is healthy. This key is only present for http health checks.

The process stats object

Example process stats object
{
  "type": "web",
  "index": 0,
  "state": "RUNNING",
  "usage": {
    "time": "2016-03-23T23:17:30.476314154Z",
    "cpu": 0.00038711029163348665,
    "mem": 19177472,
    "disk": 69705728
  },
  "host": "10.244.16.10",
  "instance_ports": [
    {
      "external": 64546,
      "internal": 8080
    }
  ],
  "uptime": 9042,
  "mem_quota": 268435456,
  "disk_quota": 1073741824,
  "fds_quota": 16384,
  "isolation_segment": "example_iso_segment",
  "details": null
}

Name Type Description
type string Process type. A unique identifier for processes belonging to an app.
index integer The zero-based index of running instances.
state string The state of the instance. Valid values are RUNNING, CRASHED, STARTING, DOWN.
usage.time datetime The time when the usage was requested.
usage.cpu number The current cpu usage of the instance.
usage.mem integer The current memory usage of the instance.
usage.disk integer The current disk usage of the instance.
host string The host the instance is running on.
instance_ports object JSON array of port mappings between the network-exposed port used to communicate with the app (external) and port opened to the running process that it can listen on (internal).
uptime integer The uptime in seconds for the instance.
mem_quota integer The maximum memory the instance is allowed to use.
disk_quota integer The maximum disk the instance is allowed to use.
fds_quota integer The maximum file descriptors the instance is allowed to use.
isolation_segment string The current isolation segment that the instance is running on. The value is null when the instance is not placed on a particular isolation segment.
details string Information about errors placing the instance. The value is null if there are no placement errors.

Get a process

Example Request
curl "https://api.example.org/v3/processes/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "relationships": {
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "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"
    }
  }
}

Definition

GET /v3/processes/:guid
GET /v3/apps/:guid/processes/:type

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Get stats for a process

Example Request
curl "https://api.example.org/v3/processes/[guid]/stats" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "resources": [
    {
      "type": "web",
      "index": 0,
      "state": "RUNNING",
      "usage": {
        "time": "2016-03-23T23:17:30.476314154Z",
        "cpu": 0.00038711029163348665,
        "mem": 19177472,
        "disk": 69705728
      },
      "host": "10.244.16.10",
      "instance_ports": [
        {
          "external": 64546,
          "internal": 8080
        }
      ],
      "uptime": 9042,
      "mem_quota": 268435456,
      "disk_quota": 1073741824,
      "fds_quota": 16384,
      "isolation_segment": "example_iso_segment",
      "details": null
    }
  ]
}

Definition

GET /v3/processes/:guid/stats
GET /v3/apps/:guid/processes/:type/stats

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List processes

Example Request
curl "https://api.example.org/v3/processes" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/processes?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/processes?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/processes?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
      "type": "web",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 5,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "health_check": {
        "type": "port",
        "data": {
          "timeout": null
        }
      },
      "relationships": {
        "revision": {
          "data": {
            "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "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"
        }
      }
    },
    {
      "guid": "3fccacd9-4b02-4b96-8d02-8e865865e9eb",
      "type": "worker",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 1,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "health_check": {
        "type": "process",
        "data": {
          "timeout": null
        }
      },
      "relationships": {
        "revision": null
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
        },
        "scale": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/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/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

Retrieve all processes the user has access to.

Definition

GET /v3/processes

Query parameters

Name Type Description
guids list of strings Comma-delimited list of process guids to filter by.
types list of strings Comma-delimited list of process types to filter by.
app_guids list of strings Comma-delimited list of app guids to filter by.
space_guids list of strings Comma-delimited list of space guids to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List processes for app

Example Request
curl "https://api.example.org/v3/apps/[guid]/processes" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
      "type": "web",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 5,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "health_check": {
        "type": "port",
        "data": {
          "timeout": null
        }
      },
      "relationships": {
        "revision": {
          "data": {
            "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
          }
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "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"
        }
      }
    },
    {
      "guid": "3fccacd9-4b02-4b96-8d02-8e865865e9eb",
      "type": "worker",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 1,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "health_check": {
        "type": "process",
        "data": {
          "timeout": null
        }
      },
      "relationships": {
        "revision": null
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
        },
        "scale": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/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/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

Retrieves all processes belonging to an app.

Definition

GET /v3/apps/:guid/processes

Query parameters

Name Type Description
guids list of strings Comma-delimited list of process guids to filter by.
types list of strings Comma-delimited list of process types to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a process

Example Request
curl "https://api.example.org/v3/processes/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "command": "rackup",
    "metadata": {
      "labels": {
        "key": "value"
      },
      "annotations": {
        "note": "detailed information"
      }
    }
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "relationships": {
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "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"
    }
  }
}

Definition

PATCH /v3/processes/:guid

Optional parameters

Name Type Description
command string or null The command used to start the process. Use null to revert to the buildpack-detected or procfile-provided start command.
health_check health check object The health check to perform on the process.
metadata.labels (experimental) label object Labels applied to the process.
metadata.annotations (experimental) annotation object Annotations applied to the process.

Permitted roles

Admin
Space Developer

Scale a process

Example Request
curl "https://api.example.org/v3/processes/[guid]/actions/scale" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "instances": 5,
    "memory_in_mb": 256,
    "disk_in_mb": 1024
  }'
Example Response
HTTP/1.1 202 OK
Content-Type: application/json

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "relationships": {
    "revision": {
      "data": {
        "guid": "885735b5-aea4-4cf5-8e44-961af0e41920"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "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"
    }
  }
}

Definition

POST /v3/processes/:guid/actions/scale
POST /v3/apps/:guid/processes/:type/actions/scale

Optional parameters

Name Type Description
instances integer The number of instances to run.
memory_in_mb integer The memory in mb allocated per instance.
disk_in_mb integer The disk in mb allocated per instance.

Permitted roles

Admin
Space Developer

Terminate a process instance

Example Request
curl "https://api.example.org/v3/processes/[guid]/instances/[index]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

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.

Definition

DELETE /v3/processes/:guid/instances/:index
DELETE /v3/apps/:guid/processes/:type/instances/:index

Permitted Roles

Admin
Space Developer

Routes

Routes are addresses that direct matched network traffic to one or more destinations. Each route is based on a domain name with additional matching criteria (host (subdomain), path, etc). Matched traffic will be distributed across all destinations, based on their configuration (round-robin by default).

The route object

Example Route object
  {
    "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
    "host": "a-hostname",
    "path": "/some_path",
    "url": "a-hostname.a-domain.com/some_path",
    "created_at": "2019-05-10T17:17:48Z",
    "updated_at": "2019-05-10T17:17:48Z",
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
        }
      },
      "domain": {
        "data": {
          "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
        }
      }
    },
    "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"
      }
    }
  }

Name Type Description
guid uuid Unique identifier for the route.
host string The hostname for the route.
Must be under 63 character long and only contain letters, numbers, dashes (-) or underscores(_).
path string The path for the route.
Must be under 128 character long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from RFC 2396.
url string The URL for the route. Combination of host, domain name, and path.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
space to-one relationship A relationship to the space containing the route. Routes can only be mapped to destinations in that space.
domain to-one relationship A relationship to the domain of the route.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the route.
metadata.annotations (experimental) annotation object Annotations applied to the route.

The destination object

Example Destination object
{
  "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
  "app": {
    "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
    "process": {
      "type": "web"
    }
  },
  "weight": null,
  "port": 8080
}

A destination represents the relationship between a route and a resource that can serve traffic (for example, the web process of an application).

When a route has destinations, that route will direct traffic to the processes represented by those destinations.

If a destination is created with a port specified, the route will direct traffic to that port on the process. A destination with port 9000 and process type api means traffic will be directed to the api process running on container port 9000.

Note that when using a custom port, the app process must be listening on the specified port for the mapping to work. Otherwise, visiting the route will result in a 404 error.

If a destination does not specify a port, the default port depends on the app lifecycle type. For buildpack apps, traffic will be directed to port 8080. For Docker apps, the first port specified in the Dockerfile will be used.

Name Type Description
guid uuid Unique identifier for the destination.
app.guid uuid Unique identifier for the app to route traffic to.
app.process.type string Type of the process belonging to the app to route traffic to.
port integer Port on the destination process to route traffic to.
weight (experimental) integer or null Percentage of traffic which will be routed to this destination. This feature is only available via the BETA Service Mesh routing plane.

Create a route

Example Request
curl "https://api.example.org/v3/routes" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "host": "a-hostname",
    "path": "/some_path",
    "relationships": {
      "domain": {
        "data": { "guid": "domain-guid" }
      },
      "space": {
        "data": { "guid": "space-guid" }
      }
    },
    "metadata": {
      "labels": { "key": "value" },
      "annotations": { "note": "detailed information"}
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
    "host": "a-hostname",
    "path": "/some_path",
    "url": "a-hostname.a-domain.com/some_path",
    "created_at": "2019-05-10T17:17:48Z",
    "updated_at": "2019-05-10T17:17:48Z",
    "metadata": {
      "labels": { "key": "value" },
      "annotations": { "note": "detailed information" }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
        }
      },
      "domain": {
        "data": {
          "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
        }
      }
    },
    "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"
      }
    }
  }

Definition

POST /v3/routes

Required parameters

Name Type Description
relationships.space to-one relationship A relationship to the space containing the route. Routes can only be mapped to destinations in that space.
relationships.domain to-one relationship A relationship to the domain of the route.

Optional parameters

Name Type Description
host string The host component for the route.
path string The path component for the route. Should begin with a /.
metadata.annotations (experimental) annotation object Annotations applied to the route.
metadata.labels (experimental) label object Labels applied to the route.

Permitted roles

Role Notes
Admin
Space Developer

Get a route

Example Request
curl "https://api.example.org/v3/routes/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
    "host": "a-hostname",
    "path": "/some_path",
    "url": "a-hostname.a-domain.com/some_path",
    "created_at": "2019-05-10T17:17:48Z",
    "updated_at": "2019-05-10T17:17:48Z",
    "metadata": {
      "labels": { },
      "annotations": { }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
        }
      },
      "domain": {
        "data": {
          "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
        }
      }
    },
    "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"
      }
    }
  }

Definition

GET /v3/routes/:guid

Permitted roles

Role Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List routes

Example Request
curl "https://api.example.org/v3/routes" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/routes?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/routes?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/routes?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
        "host": "a-hostname",
        "path": "/some_path",
        "url": "a-hostname.a-domain.com/some_path",
        "created_at": "2019-05-10T17:17:48Z",
        "updated_at": "2019-05-10T17:17:48Z",
        "metadata": {
          "labels": {},
          "annotations": {}
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
            }
          },
          "domain": {
            "data": {
              "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
            }
          }
        },
        "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"
          }
        }
      }
    ]
  }

Retrieve all routes the user has access to.

Definition

GET /v3/routes

Query parameters

Name Type Description
hosts list of strings Comma-delimited list of hostnames to filter by.
paths list of strings Comma-delimited list of paths to filter by (e.g. /path1,/path2).
domain_guids list of strings Comma-delimited list of domain guids to filter by.
space_guids list of strings Comma-delimited list of space guids to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List routes for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/routes" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "pagination": {
      "total_results": 3,
      "total_pages": 2,
      "first": {
        "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=1&per_page=2"
      },
      "last": {
        "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
      },
      "next": {
        "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2"
      },
      "previous": null
    },
    "resources": [
      {
        "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
        "host": "a-hostname",
        "path": "/some_path",
        "url": "a-hostname.a-domain.com/some_path",
        "created_at": "2019-05-10T17:17:48Z",
        "updated_at": "2019-05-10T17:17:48Z",
        "metadata": {
          "labels": {},
          "annotations": {}
        },
        "relationships": {
          "space": {
            "data": {
              "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
            }
          },
          "domain": {
            "data": {
              "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
            }
          }
        },
        "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"
          }
        }
      }
    ]
  }

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

Definition

GET /v3/apps/:guid/routes

Query parameters

Name Type Description
hosts list of strings Comma-delimited list of hostnames to filter by.
paths list of strings Comma-delimited list of paths to filter by (e.g. /path1,/path2).
domain_guids list of strings Comma-delimited list of domain guids to filter by.
space_guids list of strings Comma-delimited list of space guids to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a route

Example Request
curl "https://api.example.org/v3/routes/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "metadata": {
      "labels": {"key": "value"},
      "annotations": {"note": "detailed information"}
    }
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "cbad697f-cac1-48f4-9017-ac08f39dfb31",
    "host": "a-hostname",
    "path": "/some_path",
    "url": "a-hostname.a-domain.com/some_path",
    "created_at": "2019-05-10T17:17:48Z",
    "updated_at": "2019-05-10T17:17:48Z",
    "metadata": {
      "labels": { "key": "value" },
      "annotations": { "note": "detailed information" }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "885a8cb3-c07b-4856-b448-eeb10bf36236"
        }
      },
      "domain": {
        "data": {
          "guid": "0b5f3633-194c-42d2-9408-972366617e0e"
        }
      }
    },
    "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"
      }
    }
  }

Definition

PATCH /v3/routes/:guid

Optional parameters

Name Type Description Default
metadata.labels (experimental) label object Labels applied to the route.
metadata.annotations (experimental) annotation object Annotations applied to the route.

Permitted roles

Role Notes
Admin
Space Developer

Delete a route

Example Request
curl "https://api.example.org/v3/routes/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/routes/:guid

Permitted roles

Role Notes
Admin
Space Developer

Check reserved routes for a domain

Example Request
curl "https://api.example.org/v3/domains/[guid]/route_reservations" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  { "matching_route": true }

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.

Definition

GET /v3/domains/:guid/route_reservations

Query parameters

Name Type Description
host string Hostname to filter by. Defaults to empty string if not provided.
path string Path to filter by. Defaults to empty string if not provided.

Permitted roles

Role Notes
Admin
Admin Read-Only
Global Auditor
Org Auditor
Org Billing Manager Can only check if routes exist for a domain without an organization relationship.
Org Manager
Space Auditor
Space Developer
Space Manager

List destinations for a route

Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "destinations": [
      {
        "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
        "app": {
          "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
          "process": {
            "type": "web"
          }
        },
        "weight": null,
        "port": 8080
      },
      {
        "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "weight": null,
        "port": 9000
      }
    ],
    "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"
      }
    }
  }

Retrieve all destinations associated with a route.

Definition

GET /v3/routes/:guid/destinations

Permitted roles

Role Notes
Admin Read-Only
Admin
Global Auditor
Org Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Insert destinations for a route

Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations" \
  -X POST \
  -H "Authorization: bearer [token]"
  -d '{
    "destinations": [
      {
        "app": {
          "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
        }
      },
      {
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "port": 9000
      }
    ]
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "destinations": [
      {
        "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
        "app": {
          "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
          "process": {
            "type": "web"
          }
        },
        "weight": null,
        "port": 8080
      },
      {
        "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "weight": null,
        "port": 9000
      }
    ],
    "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"
      }
    }
  }

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

Note that weighted destinations cannot be added with this endpoint. To add weighted destinations, replace all destinations for a route at once using the replace destinations endpoint.

Definition

POST /v3/routes/:guid/destinations

Required parameters

Name Type Description
destinations array of destination objects List of destinations to add to route. Destinations without process.type specified will get process type "web" by default.

Permitted roles

Role
Admin
Space Developer

Replace all destinations for a route

Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations" \
  -X PATCH \
  -H "Authorization: bearer [token]"
  -d '{
    "destinations": [
      {
        "app": {
          "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
        },
        "weight": 61
      },
      {
        "app": {
          "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
          "process": {
            "type": "api"
          }
        },
        "weight": 39,
        "port": 9000
      }
    ]
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "destinations": [
    {
      "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
      "app": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
        "process": {
          "type": "web"
        }
      },
      "weight": 61,
      "port": 8080
    },
    {
      "guid": "fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5",
      "app": {
        "guid": "01856e12-8ee8-11e9-98a5-bb397dbc818f",
        "process": {
          "type": "api"
        }
      },
      "weight": 39,
      "port": 9000
    }
  ],
  "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"
    }
  }
}

Replaces all destinations for a route, removing any destinations not included in the provided list.

If using weighted destinations, 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.

Definition

PATCH /v3/routes/:guid/destinations

Required parameters

Name Type Description
destinations array of destination objects List of destinations use for route. Destinations without process.type specified will get process type "web" by default.

Permitted roles

Role
Admin
Space Developer

Remove destination for a route

Example Request
curl "https://api.example.org/v3/routes/[guid]/destinations/[destination_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

Remove a destination from a route.

Definition

DELETE /v3/routes/:guid/destinations/:destination_guid

Permitted roles

Role Notes
Admin
Space Developer

Delete unmapped routes for a space

Example Request
curl "https://api.example.org/v3/spaces/[guid]/routes?unmapped=true" \
  -X DELETE\
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

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

Definition

DELETE /v3/spaces/:guid/routes?unmapped=true

Permitted roles

Role Notes
Admin
Space Developer

Note: unmapped=true is a required query parameter; always include it.

Service Instances

An instantiation of a service offering.

The service instance object

Example Service Instance object
{
  "guid": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
  "created_at": "2017-11-17T13:54:21Z",
  "updated_at": "2017-11-17T13:54:21Z",
  "name": "my_service_instance",
  "relationships": {
    "space": {
      "data": {
        "guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
      }
    }
  },
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "links": {
    "space": {
      "href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
    }
  }
}

Name Type Description
name string Name of the service instance.
guid uuid Unique identifier for the service instance.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
relationships.space to-one relationship The space the service instance is contained in.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the service instance.
metadata.annotations (experimental) annotation object Annotations applied to the service instance.

List service instances

Example Request
curl "https://api.example.org/v3/service_instances" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "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": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
      "created_at": "2017-11-17T13:54:21Z",
      "updated_at": "2017-11-17T13:54:21Z",
      "name": "my_service_instance",
      "relationships": {
        "space": {
          "data": {
            "guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
          }
        }
      },
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "links": {
        "space": {
          "href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
        }
      }
    }
  ]
}

This endpoint retrieves the service instances the user has access to. At the moment, this endpoint only returns managed service instances. This may change in the future.

This includes access granted by service instance sharing.

Definition

GET /v3/service_instances

Query parameters

Name Type Description
names list of strings Comma-delimited list of service instance names to filter by.
space_guids list of strings Comma-delimited list of space guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List shared spaces relationship

Example Request
curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
    }
  }
}

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

Definition

GET /v3/service_instances/:guid/relationships/shared_spaces

Permitted roles (in the service instance’s originating space)

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a service instance

Example Request
curl "https://api.example.org/v3/service_instances/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "85ccdcad-d725-4109-bca4-fd6ba062b5c8",
  "created_at": "2017-11-17T13:54:21Z",
  "updated_at": "2017-11-17T13:54:21Z",
  "name": "my_service_instance",
  "relationships": {
    "space": {
      "data": {
        "guid": "ae0031f9-dd49-461c-a945-df40e77c39cb"
      }
    }
  },
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "links": {
    "space": {
      "href": "https://api.example.org/v3/spaces/ae0031f9-dd49-461c-a945-df40e77c39cb"
    }
  }
}

Definition

PATCH /v3/service_instances/:guid

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the service_instance.
metadata.annotations (experimental) annotation object Annotations applied to the service_instance.

Permitted roles

Admin
Space Developer

Share a service instance to other spaces

Example Request
curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "data": [
      { "guid":"space-guid-1" },
      { "guid":"space-guid-2" }
    ]
  }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
    }
  }
}

This endpoint shares the service instance with the specified spaces. In order to share into a space the requesting user must be a space developer in the target space.

Definition

POST /v3/service_instances/:guid/relationships/shared_spaces

Required parameters

Name Type Description
data to-many relationship Shared space relationships. Each space will have this service instance shared to it.

Permitted roles

Admin
Space Developer

Unshare a service instance from another space

Example Request
curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces/[space_guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

This endpoint unshares the service instance with the specified space. This will automatically unbind any applications bound to this service instance in the specified space.

Definition

DELETE /v3/service_instances/:guid/relationships/shared_spaces/:space_guid

Permitted roles

Admin
Space Developer

Spaces

Every application and service is scoped to a space. Each org contains at least one space. A space provides users with access to a shared location for application development, deployment, and maintenance.

The space object

Example Space object
{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Name Type Description
guid uuid Unique identifier for the space.
name string Name of the space.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
relationships.organization to-one relationship The organization the space is contained in.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the space.
metadata.annotations (experimental) annotation object Annotations applied to the space.

Create a space

Example Request
curl "https://api.example.org/v3/spaces" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-space",
    "relationships": {
      "organization": {
        "data": {
          "guid": "[org-guid]"
        }
      }
    }
  }'

Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/spaces

Required parameters

Name Type Description
name string Space name
relationships.organization to-one relationship A relationship to an organization.

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the space.
metadata.annotations (experimental) annotation object Annotations applied to the space.

Permitted roles

Admin
Org Manager

Get a space

Example Request
curl "https://api.example.org/v3/spaces/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

This endpoint retrieves the specified space object.

Definition

GET /v3/spaces/:guid

Query parameters

Name Type Description
include string Experimental - Optionally include additional related resources in the response.
Valid value is org.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List spaces

Example Request
curl "https://api.example.org/v3/spaces" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-type: application/json

{
  "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": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z",
      "name": "space1",
      "relationships": {
        "organization": {
          "data": {
            "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
        },
        "organization": {
          "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
      "created_at": "2017-02-02T00:14:30Z",
      "updated_at": "2017-02-02T00:14:30Z",
      "name": "space2",
      "relationships": {
        "organization": {
          "data": {
            "guid": "b4ce91bd-31df-4b7d-8fd4-21a6b533276b"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f"
        },
        "organization": {
          "href": "https://api.example.org/v3/organizations/b4ce91bd-31df-4b7d-8fd4-21a6b533276b"
        }
      },
      "metadata": {
        "labels": {},
        "annotations": {}
      }
    }
  ]
}

Retrieve all spaces the user has access to.

Definition

GET /v3/spaces

Query parameters

Name Type Description
names list of strings Comma-delimited list of space names to filter by.
guids list of strings Comma-delimited list of space guids to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at, name.
label_selector string Experimental - A query string containing a list of label selector requirements.
include string Experimental - Optionally include a list of unique related resources in the response.
Valid value is org.

Permitted roles

All Roles

Update a space

Example Request
curl "https://api.example.space/v3/spaces/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "name": "new-space-name" }'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "name": "my-space",
  "relationships": {
    "organization": {
      "data": {
        "guid": "e00705b9-7b42-4561-ae97-2520399d2133"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920"
    },
    "organization": {
      "href": "https://api.example.org/v3/organizations/e00705b9-7b42-4561-ae97-2520399d2133"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

PATCH /v3/spaces/:guid

Optional parameters

Name Type Description
name string New space name
metadata.labels (experimental) label object Labels applied to the space.
metadata.annotations (experimental) annotation object Annotations applied to the space.

Permitted roles

Admin
Org Manager
Space Manager

Delete a space

Example Request
curl "https://api.example.org/v3/spaces/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/spaces/:guid

Permitted roles

Role Notes
Admin
Org Manager

Get assigned isolation segment

Example Request
curl "https://api.example.org/v3/spaces/[guid]/relationships/isolation_segment" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
  },
  "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"
    }
  }
}

Definition

GET /v3/spaces/:guid/relationships/isolation_segment

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Manage isolation segment

Example Request
curl "https://api.example.org/v3/spaces/[guid]/relationships/isolation_segment" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "guid": "[iso-seg-guid]"
    }
   }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
  },
  "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"
    }
  }
}

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

Definition

PATCH /v3/spaces/:guid/relationships/isolation_segment

Required parameters

Name Type Description
data to-one relationship Isolation segment relationship. Apps will run in this isolation segment. Set data to null to remove the relationship.

Permitted roles

Admin
Org Manager

Stacks

Stacks are the base operating system and file system that your application will execute in. A stack is how you configure applications to run against different operating systems (like Windows or Linux) and different versions of those operating systems (like Windows 2012 or Windows 2016).

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

Stacks are not used for apps with a Docker lifecycle.

The stack object

Example Stack object
{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Name Type Description
name string The name of the stack
description string The description of the stack
guid uuid Unique identifier for the stack.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
metadata.labels (experimental) label object Labels applied to the stack.
metadata.annotations (experimental) annotation object Annotations applied to the stack.
links links object Links to related resources.

Create a stack

Example Request
curl "https://api.example.org/v3/stacks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my-stack",
    "description": "Here is my stack!",
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

POST /v3/stacks

Required parameters

Name Type Description
name string Name of the stack. Must be unique and no longer than 250 characters.

Optional parameters

Name Type Description Default
description string Description of the stack. Must no longer than 250 characters. null
metadata.labels (experimental) label object Labels applied to the stack.
metadata.annotations (experimental) annotation object Annotations applied to the stack.

Permitted roles

Admin

Get a stack

Example Request
curl "https://api.example.org/v3/stacks/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { },
     "annotations": { }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

GET /v3/stacks/:guid

Permitted roles

All Roles

List stacks

Example Request
curl "https://api.example.org/v3/stacks" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/stacks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/stacks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/stacks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
      "created_at": "2018-11-09T22:43:28Z",
      "updated_at": "2018-11-09T22:43:28Z",
      "name": "my-stack-1",
      "description": "This is my first stack!",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
        }
      }
    },
    {
      "guid": "81c916c9-c2f9-440e-8e73-102e79c4704h",
      "created_at": "2018-11-09T22:43:29Z",
      "updated_at": "2018-11-09T22:43:29Z",
      "name": "my-stack-2",
      "description": "This is my second stack!",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/stacks/81c916c9-c2f9-440e-8e73-102e79c4704h"
        }
      }
    }
  ]
}


Retrieve all stacks.

Definition

GET /v3/stacks

Query parameters

Name Type Description
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
names list of strings Comma-delimited list of app names to filter by.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

Update a stack

Example Request
curl "https://api.example.org/v3/stacks/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
   "created_at": "2018-11-09T22:43:28Z",
   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
   "metadata": {
     "labels": { "key": "value" },
     "annotations": { "note": "detailed information" }
   },
   "links": {
      "self": {
         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
      }
   }
}

Definition

PATCH /v3/stacks/:guid

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the stack.
metadata.annotations (experimental) annotation object Annotations applied to the stack.

Permitted roles

Admin
Space Developer

Delete a stack

Example Request
curl "https://api.example.org/v3/stacks/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

Definition

DELETE /v3/stacks/:guid

Permitted roles

Admin

Tasks

Tasks are one-off jobs that are intended to perform a task, stop, and be cleaned up, freeing up resources.

Examples of this include database migrations, sending things, and batch jobs.

The task object

Example Task object
{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Name Type Description
sequence_id integer User-facing id of the task. This number is unique for every task associated with a given app.
name string Name of the task.
command string Command that will be executed. This field may be excluded based on a user’s role.
disk_in_mb integer Amount of disk to allocate for the task in MB.
memory_in_mb integer Amount of memory to allocate for the task in MB.
state string State of the task. Possible states are PENDING, RUNNING, SUCCEEDED, CANCELING, and FAILED
droplet_guid uuid The guid of the droplet that will be used to run the command.
result object Results from the task
result.failure_reason string Null if the task succeeds, contains the error message if it fails.
guid uuid Unique identifier for the task.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.
metadata.labels (experimental) label object Labels applied to the task.
metadata.annotations (experimental) annotation object Annotations applied to the task.

Create a task

Example Request with Command
curl "https://api.example.org/v3/apps/[guid]/tasks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "command": "rake db:migrate" }'
Example Request with Template Process
curl "https://api.example.org/v3/apps/[guid]/tasks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "template": { "process": {"guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e"} } }'
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Definition

POST /v3/apps/:guid/tasks

Required parameters

Name Type Description
command[1] string Command that will be executed. NOTE: optional if a template.process.guid is provided

Optional parameters

Name Type Description Default
name string Name of the task. auto-generated
disk_in_mb[1] integer Amount of disk to allocate for the task in MB. operator-configured default_app_disk_in_mb
memory_in_mb[1] integer Amount of memory to allocate for the task in MB. operator-configured default_app_memory
droplet_guid uuid The guid of the droplet that will be used to run the command. the app’s current droplet
template.process.guid (experimental) uuid The guid of the process that will be used as a template. null
metadata.labels (experimental) label object Labels applied to the package.
metadata.annotations (experimental) annotation object Annotations applied to the package.

1 If not provided, and a template.process.guid is provided, this field will use the value from the process with the given guid.

Permitted roles

Admin
Space Developer

Get a task

Example Request
curl "https://api.example.org/v3/tasks/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

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

Definition

GET /v3/tasks/:guid

Permitted roles

Admin Read-Only
Admin
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List tasks

Example Request
curl "https://api.example.org/v3/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/tasks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/tasks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/tasks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "sequence_id": 1,
      "name": "hello",
      "state": "SUCCEEDED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": null
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
    {
      "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
      "sequence_id": 2,
      "name": "migrate",
      "state": "FAILED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": "Exited with status 1"
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    }
  ]
}

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

Definition

GET /v3/tasks

Query parameters

Name Type Description
guids list of strings Comma-delimited list of task guids to filter by.
names list of strings Comma-delimited list of task names to filter by.
states list of strings Comma-delimited list of task states to filter by.
app_guids list of strings Comma-delimited list of app guids to filter by.
space_guids list of strings Comma-delimited list of space guids to filter by.
organization_guids list of strings Comma-delimited list of organization guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

All Roles

List tasks for an app

Example Request
curl "https://api.example.org/v3/apps/:guid/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "sequence_id": 1,
      "name": "hello",
      "state": "SUCCEEDED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": null
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
    {
      "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
      "sequence_id": 2,
      "name": "migrate",
      "state": "FAILED",
      "memory_in_mb": 512,
      "disk_in_mb": 1024,
      "result": {
        "failure_reason": "Exited with status 1"
      },
      "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
      "metadata": {
        "labels": { },
        "annotations": { }
      },
      "created_at": "2016-05-04T17:00:41Z",
      "updated_at": "2016-05-04T17:00:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "cancel": {
          "href": "https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel",
          "method": "POST"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    }
  ]
}

Retrieve tasks for an app the user has access to. The command field may be excluded in the response based on the user’s role.

Definition

GET /v3/apps/:guid/tasks

Query parameters

Name Type Description
guids list of strings Comma-delimited list of task guids to filter by.
names list of strings Comma-delimited list of task names to filter by.
states list of strings Comma-delimited list of task states to filter by.
sequence_ids list of strings Comma delimited list of sequence ids to filter by. Valid values are integers >= 1
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin Read-Only
Admin
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a task

Example Request
curl "https://api.example.org/v3/tasks/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

Definition

PATCH /v3/tasks/:guid

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the task.
metadata.annotations (experimental) annotation object Annotations applied to the task.

Permitted roles

Admin
Space Developer

Cancel a task

Example Request
curl "https://api.example.org/v3/tasks/[guid]/actions/cancel" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "sequence_id": 1,
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "CANCELING",
  "memory_in_mb": 512,
  "disk_in_mb": 1024,
  "result": {
    "failure_reason": null
  },
  "droplet_guid": "740ebd2b-162b-469a-bd72-3edb96fabd9a",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "created_at": "2016-05-04T17:00:41Z",
  "updated_at": "2016-05-04T17:00:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "cancel": {
      "href": "https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "method": "POST"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

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.

Definition

POST /v3/tasks/:guid/actions/cancel
PUT /v3/tasks/:guid/cancel (Deprecated)

Permitted roles

Admin
Space Developer

Experimental Resources

App Features

The app feature object

Example App Feature object
{
  "name": "ssh",
  "description": "Enable SSHing into the app.",
  "enabled": true
}

Name Type Description
name string Name of the app feature.
description string Description of the app feature.
enabled boolean Denotes whether or not the app feature is enabled.

Supported app features

Name Description
ssh Enable SSHing into the app.
revisions Enable versioning of an application (experimental)

Get an app feature

Example Request
curl "https://api.example.org/v3/apps/[guid]/features/[name]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "ssh",
  "description": "Enable SSHing into the app.",
  "enabled": true
}

Definition

GET /v3/apps/:guid/features/:name

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List app features

Example Request
curl "https://api.example.org/v3/apps/[guid]/features" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "resources": [
    {
      "name": "ssh",
      "description": "Enable SSHing into the app.",
      "enabled": true
    },
    {
      "name": "revisions",
      "description": "Enable versioning of an application (experimental)",
      "enabled": false
    }
  ],
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
    "last": { "href": "/v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features" },
    "next": null,
    "previous": null
  }
}

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

Definition

GET /v3/apps/:guid/features

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update an app feature

Example Request
curl "https://api.example.org/v3/apps/[guid]/features/[name]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "enabled": false }'
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "ssh",
  "description": "Enable SSHing into the app.",
  "enabled": true
}

Definition

PATCH /v3/apps/:guid/features/:name

Required parameters

Name Type Description
enabled boolean Denotes whether or not the app feature should be enabled.

Permitted roles

Admin
Space Developer

App Manifest

The app manifest is a method for applying bulk configuration to an app and its underlying processes.

The app manifest specification

Example Manifest
---
applications:
- buildpacks:
    - ruby_buildpack
    - java_buildpack
  env:
    VAR1: value1
    VAR2: value2
  routes:
  - route: route.example.com
  - route: another-route.example.com
  services:
  - my-service1
  - my-service2
  - name: my-service-with-arbitrary-params
    parameters:
      key1: value1
      key2: value2
  stack: cflinuxfs3
  metadata:
    annotations:
      contact: "[email protected] [email protected]"
    labels:
      sensitive: true
  processes:
  - type: web
    command: start-web.sh
    disk_quota: 512M
    health-check-http-endpoint: /healthcheck
    health-check-type: http
    health-check-invocation-timeout: 10
    instances: 3
    memory: 500M
    timeout: 10
  - type: worker
    command: start-worker.sh
    disk_quota: 1G
    health-check-type: process
    instances: 2
    memory: 256M
    timeout: 15
  sidecars:
  - name: authenticator
    process_types: [ 'web', 'worker' ]
    command: bundle exec run-authenticator
    memory: 800M
  - name: upcaser
    process_types: [ 'worker' ]
    command: ./tr-server
    memory: 900M

App-level configuration

This configuration is specified at the top-level and applies to all of the app’s processes.

Field Description
buildpacks Must be an Array.
a) An empty array, which will automatically select the appropriate default buildpack according to the coding language.
b) An array of one or more URLs pointing to buildpacks.
c) An array of one or more installed buildpack names.
Replaces the legacy buildpack field.
env A key-value hash of environment variables to be used for the app when running.
no-route Boolean value. Removes the app’s routes if true; ignored if false. Cannot be used in conjunction with the routes attribute when set to true.
processes List of configurations for individual process types. See Process-level configuration.
random-route Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified.
routes An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path
services An array of service-instances to bind to the app. See Service-level configuration.
sidecars An array of configurations for individual sidecars. See Sidecar-level configuration.
stack The root filesystem to use with the buildpack, for example cflinuxfs3.
metadata.labels (experimental) Labels applied to the app.
metadata.annotations (experimental) Annotations applied to the app.
buildpack DEPRECATED in favor of the buildpacks field above.
a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language.
b) A URL pointing to a buildpack.
c) Name of an installed buildpack.

Process-level configuration

This configuration is for the individual process. Each process is created if it does not already exist.

With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.

If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.

Field Description
type (Required) Process type. The identifier for the processes to be configured.
command The command used to start the process. This overrides start commands from Procfiles and buildpacks.
disk_quota The disk limit for all instances of the web process.
This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
health-check-http-endpoint Endpoint called to determine if the app is healthy.
health-check-invocation-timeout The timeout in seconds for individual health check requests for http and port health checks.
health-check-type Type of health check to perform. none is deprecated and an alias to process.
instances The number of instances to run.
memory The memory limit for all instances of the web process.
This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
timeout Time in seconds at which the health-check will report failure.

Service-level configuration

This configuration is creating new service bindings between the app and a service instance. The services field can take either an array of service instance name strings or an array of the following service-level fields.

Field Description
name (Required) Service instance name. The name of the service instance to be bound to.
parameters A map of arbitrary key/value pairs to send to the service broker during binding.

Sidecar-level configuration

This configuration is for the individual sidecar. Each sidecar is created if it does not already exist.

Field Description
name (Required) Sidecar name. The identifier for the sidecars to be configured.
command The command used to start the sidecar.
process_types List of processes to associate sidecar with.
memory Memory in mb that the sidecar will be allocated.

Generate an app manifest

Example Request
curl "https://api.example.org/v3/apps/[guid]/manifest" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/x-yaml

---
applications:
- name: my-app
  stack: cflinuxfs3
  routes:
  - route: my-app.example.com
  processes:
  - type: web
    instances: 2
    memory: 512M
    disk_quota: 1024M
    health-check-type: port

Generate a manifest for an app and its underlying processes.

Definition

GET /v3/apps/:guid/manifest

Permitted Roles

Admin
Admin Read-Only
Space Developer

Apply an app manifest

Example Request
curl "https://api.example.org/v3/apps/[guid]/actions/apply_manifest" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/x-yaml" \
  --data-binary @/path/to/manifest.yml
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Apply changes specified in a manifest to an app and its underlying processes. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.

Definition

POST /v3/apps/:guid/actions/apply_manifest

Permitted Roles

Admin
Space Developer

App Restart

Restart an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/actions/restart" \
-X POST \
-H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "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": "cflinuxfs3"
    }
  },
  "relationships": {
    "space": {
      "data": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "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"
    }
  },
  "metadata": {
    "labels": {},
    "annotations": {}
  }
}

Definition

POST /v3/apps/:guid/actions/restart

Permitted roles

Admin
Space Developer

App SSH Enabled

Get app SSH enabled

Example Request
curl "https://api.example.org/v3/apps/:guid/ssh_enabled" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "enabled": false,
  "reason": "Disabled globally"
}

Definition

GET /v3/apps/:guid/ssh_enabled

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Deployments

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

They can either:

It is possible to use rolling deployments for applications without incurring downtime. This is different from the traditional method of pushing app updates which performs start/stop deployments.

The deployment object

Example Deployment object

{
  "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
  "state": "DEPLOYING",
  "status": {
    "value": "DEPLOYING",
    "reason": null
  },
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "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"
    }
  }
}

Name Type Description
state string (deprecated) The state of the deployment. Valid values are DEPLOYING, DEPLOYED, CANCELING, or CANCELED. This field will be removed in the future; use the status fields to determine deployment state instead.
status.value string The current status of the deployment. Valid values are DEPLOYING, CANCELING, and FINALIZED (meaning finished, either successfully or not).
status.reason string or null The reason for the final status of the deployment. Valid values are DEPLOYED, CANCELED, SUPERSEDED (another deployment created for app before completion), DEGENERATE (the deployment was created incorrectly by the system).

This attribute is only set if the deployment has status.value of FINALIZED. If the deployment is still in progress, this field will be set to null.
guid uuid Unique identifier for the deployment.
relationships.app to-one relationship The app the deployment is updating.
droplet object The droplet the deployment is transitioning the app to.
previous_droplet object The app’s current droplet before the deployment was created.
new_processes array List of processes created as part of the deployment
revision object The revision the deployment is transitioning the app to.
metadata.labels (experimental) label object Labels applied to the deployment.
metadata.annotations (experimental) annotation object Annotations applied to the deployment.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.

Create a deployment

Example Request with Droplet
curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "droplet": {
    "guid": "[droplet-guid]"
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "[app-guid]"
      }
    }
  }
}'
Example Request with Revision
curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "revision": {
    "guid": "[revision-guid]"
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "[app-guid]"
      }
    }
  }
}'
Example Response
HTTP/1.1 201 OK
Content-Type: application/json


{
  "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
  "state": "DEPLOYING",
  "status": {
    "value": "DEPLOYING",
    "reason": null
  },
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "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"
    }
  }
}

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.

Definition

POST /v3/deployments

Required parameters

Name Type Description
relationships.app to-one relationship The app to deploy a droplet for.

Optional parameters

Name Type Description Default
droplet[1] object The droplet to deploy for the app. This will update the app’s current droplet to this droplet The app’s current droplet
revision[1] object The revision whose droplet to deploy for the app. This will update the app’s current droplet to this droplet
metadata.labels (experimental) label object Labels applied to the deployment.
metadata.annotations (experimental) annotation object Annotations applied to the deployment.

1 Only a droplet or a revision may be provided, not both.

Permitted roles

Admin
Space Developer

Get a deployment

Example Request
curl "https://api.example.org/v3/deployments/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json


{
  "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
  "state": "DEPLOYING",
  "status": {
    "value": "DEPLOYING",
    "reason": null
  },
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { },
    "annotations": { }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "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"
    }
  }
}

Definition

GET /v3/deployments/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List deployments

Example Request
curl "https://api.example.org/v3/deployments" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/deployments?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/deployments?page=1&per_page=2"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
      "state": "DEPLOYED",
      "status": {
        "value": "FINALIZED",
        "reason": "DEPLOYED"
      },
      "droplet": {
        "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
      },
      "previous_droplet": {
        "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
      },
      "new_processes": [
        {
          "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
          "type": "web-deployment-59c3d133-2b83-46f3-960e-7765a129aea4"
        }
      ],
      "revision": {
        "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
        "version": 1
      },
      "created_at": "2018-04-25T22:42:10Z",
      "updated_at": "2018-04-25T22:42:10Z",
      "metadata": {
        "labels": {},
        "annotations": {}
      },
      "relationships": {
        "app": {
          "data": {
            "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
          }
        }
      },
      "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"
        }
      }
    }
  ]
}

Retrieve all deployments the user has access to.

Definition

GET /v3/deployments

Query parameters

Name Type Description
app_guids list of strings Comma-delimited list of app guids to filter by.
states list of strings Comma-delimited list of states to filter by.
status_reasons list of strings Comma-delimited list of status reasons to filter by.
Valid values include DEPLOYED, CANCELED, SUPERSEDED, and a blank value.
status_values list of strings Comma-delimited list of status values to filter by.
Valid values include DEPLOYING and FINALIZED.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.
label_selector string Experimental - A query string containing a list of label selector requirements.

Permitted roles

Admin Read-Only
Admin
Global Auditor
Org Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a deployment

Example Request
curl "https://api.example.org/v3/deployments/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json


{
  "guid": "59c3d133-2b83-46f3-960e-7765a129aea4",
  "state": "DEPLOYING",
  "status": {
    "value": "DEPLOYING",
    "reason": null
  },
  "droplet": {
    "guid": "44ccfa61-dbcf-4a0d-82fe-f668e9d2a962"
  },
  "previous_droplet": {
    "guid": "cc6bc315-bd06-49ce-92c2-bc3ad45268c2"
  },
  "new_processes": [
    {
      "guid": "fd5d3e60-f88c-4c37-b1ae-667cfc65a856",
      "type": "web"
    }
  ],
  "revision": {
    "guid": "56126cba-656a-4eba-a81e-7e9951b2df57",
    "version": 1
  },
  "created_at": "2018-04-25T22:42:10Z",
  "updated_at": "2018-04-25T22:42:10Z",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "relationships": {
    "app": {
      "data": {
        "guid": "305cea31-5a44-45ca-b51b-e89c7a8ef8b2"
      }
    }
  },
  "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"
    }
  }
}

Definition

PATCH /v3/deployments/:guid

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the deployment.
metadata.annotations (experimental) annotation object Annotations applied to the deployment.

Permitted roles

Admin
Space Developer

Cancel a deployment

Example Request
curl "https://api.example.org/v3/deployments/[guid]/actions/cancel" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK

Definition

POST /v3/deployments/:guid/actions/cancel

Permitted roles

Admin
Space Developer

Resource Matches

This endpoint matches given resource SHA-1 / file size pairs against the Cloud Controller cache, and reports the subset that describes already cached files. This is usually used to avoid uploading duplicate files when pushing an app which has only been partially changed. The path and mode fields are not used when matching.

When uploading package bits, the response from this endpoint should be used as the resources form field. As such, it is useful to include the path and mode fields for each resource even though they are not used when determining a resource match.

Cloud Foundry operators may set minimum / maximum file sizes to match against. If the file size provided is outside this range, it will not be matched against.

The resource match object

Example Resource Match object
{
  "resources": [
    {
      "checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
      "size_in_bytes": 1,
      "path": "path/to/file",
      "mode": "644"
    }
  ]
}

Name Type Description
checksum.value string (Required) SHA-1 hash of file
size_in_bytes integer (Required) Size of file in bytes
path string Path to the file, relative to app root
mode string File mode, i.e. POSIX file permissions. Defaults to 0744

Create a resource match

Example Request
curl "https://api.example.org/v3/resource_matches" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
        "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"
          }
        ]
      }'

Example Response
HTTP/1.1 201 OK
Content-Type: application/json

{
  "resources": [
    {
      "checksum": { "value": "a9993e364706816aba3e25717850c26c9cd0d89d" },
      "size_in_bytes": 1,
      "path": "path/to/file",
      "mode": "644"
    }
  ]
}

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

Definition

POST /v3/resource_matches

Required parameters

Name Type Description
resources array of resource_object List of resources to check for in the resource cache

Permitted roles

All Roles

Revisions

Revisions represent code used by an application at a specific time. The most recent revision for a running application represents code and configuration currently running in Cloud Foundry.

Revision are created when the following is changed:

Each time a new revision is created the reason(s) for the revisions creation will be appended to its description field.

By default the cloud foundry API retains at most 100 revisions per app.

The revision object

Example Revision object
{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "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"
    }
  }
}

Name Type Description
guid uuid Unique identifier for the revision.
version integer Human-readable identifier for the revision. Starts at 1, increments by 1 for each new revision of the app, and rolls back over to 1 at 9999.
droplet object The droplet used by a process running the revision.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
description string A short description of the reason for revision.
metadata.labels (experimental) label object Labels applied to the revision.
metadata.annotations (experimental) annotation object Annotations applied to the revision.
links links object Links to related resources.

Get a revision

Example Request
curl "https://api.example.org/v3/revisions/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "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"
    }
  }
}

Definition

GET /v3/revisions/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List revisions for an app

Example Request
curl "https://api.example.org/v3/apps/:guid/revisions" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "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": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "version": 1,
      "droplet": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      },
      "description": "Initial revision.",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "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"
        }
      }
    }
  ]
}

Retrieve revisions for an app the user has access to.

Definition

GET /v3/apps/:guid/revisions

Query parameters

Name Type Description
versions list of strings Comma-delimited list of revision versions to filter by.
label_selector string Experimental - A query string containing a list of label selector requirements.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List deployed revisions for an app

Example Request
curl "https://api.example.org/v3/apps/:guid/revisions/deployed" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "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": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "version": 1,
      "droplet": {
        "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
      },
      "description": "Initial revision.",
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "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"
        }
      }
    }
  ]
}

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

Definition

GET /v3/apps/:guid/revisions/deployed

Query parameters

Name Type Description
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a revision

Example Request
curl "https://api.example.org/v3/revisions/[revguid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}}}'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "version": 1,
  "droplet": {
    "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16"
  },
  "description": "Initial revision.",
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z",
  "metadata": {
    "labels": { "key": "value" },
    "annotations": { "note": "detailed information" }
  },
  "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"
    }
  }
}

Definition

PATCH /v3/revisions/:guid

Optional parameters

Name Type Description
metadata.labels (experimental) label object Labels applied to the revision.
metadata.annotations (experimental) annotation object Annotations applied to the revision.

Permitted roles

Admin
Space Developer

Service Bindings

Service bindings are relations between a service instance and an app; to use a service instance with an app, you must first bind them together.

Not all services support binding, as some services deliver value to users directly without integration with an application.

The service binding object

Example Service Binding object
{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "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"
    }
  }
}

Name Type Description
type string Service binding type. Valid value is app.
data object Data returned from the service broker for the service instance. Valid values are credentials, syslog_drain_url and (experimental) volume_mounts.
guid uuid Unique identifier for the service binding.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.

Create a service binding

Example Request
curl "https://api.example.org/v3/service_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "app",
    "relationships": {
      "app": {
        "data": {
          "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      },
      "service_instance": {
        "data": {
          "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
        }
      }
    },
    "data": {
      "parameters": {
        "some_object_id": "for_the_service_broker"
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "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"
    }
  }
}

Definition

POST /v3/service_bindings

Required parameters

Name Type Description
type string Service binding type. Valid value is app.
relationships.app to-one relationship A relationship to an app.
relationships.service_instance to-one relationship A relationship to a service_instance.

Optional parameters

Name Type Description Default
data.parameters object Additional configuration parameters for the service binding. {}

Permitted roles

Admin
Space Developer

Get a service binding

Example Request
curl "https://api.example.org/v3/service_bindings/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.example.org",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "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"
    }
  }
}

Definition

GET /v3/service_bindings/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List service bindings

Example Request
curl "https://api.example.org/v3/service_bindings" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_bindings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_bindings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "type": "app",
      "data": {
        "credentials": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "syslog_drain_url": "syslog://drain.url.example.org",
        "volume_mounts": []
      },
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        },
        "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"
        }
      }
    },
    {
      "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
      "type": "app",
      "data": {
        "credentials": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "syslog_drain_url": "syslog://drain.url.example.org",
        "volume_mounts": []
      },
      "created_at": "2015-11-13T17:02:56Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "service_instance": {
          "href": "https://api.example.org/v3/service_instances/8bf356j3-9e18-45b1-3333-124163f31f9e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      }
    }
  ]
}

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

Definition

GET /v3/service_bindings

Query parameters

Name Type Description
app_guids list of strings Comma-delimited list of app guids to filter by.
service_instance_guids list of strings Comma-delimited list of service_instance guids to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.

Permitted roles

All Roles

Delete a service binding

Example Request
curl "https://api.example.org/v3/service_bindings/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

Definition

DELETE /v3/service_bindings/:guid

Permitted Roles

Admin
Space Developer

Service Brokers

Service brokers manage the lifecycle of services. On behalf of users, Cloud Controller will interact with service brokers to provision, get access to and manage access to the services and plans they offer.

The service broker object

Example Service Broker object
{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "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": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

Name Type Description
guid uuid Unique identifier for the service broker.
name string Name of the service broker.
url string URL of the service broker.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
links links object Links to related resources.

Get a service broker

Example Request
curl "https://api.example.org/v3/service_brokers/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "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": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

This endpoint retrieves the service broker by GUID.

Definition

GET /v3/service_brokers/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Space Developer

List service brokers

Example Request
curl "https://api.example.org/v3/service_brokers" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/service_brokers?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/service_brokers?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "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": {} ,
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        }
      }
    },
    {
      "guid": "7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62",
      "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": "2f35885d-0c9d-4423-83ad-fd05066f8576"
          }
        }
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/service_brokers/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "space": {
          "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  ]
}

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

Definition

GET /v3/service_brokers

Query parameters

Name Type Description
names list of strings Comma-delimited list of service broker names to filter by.
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
space_guids list of strings Comma-delimited list of space GUIDs to filter by.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at, name.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Space Developer

Create a service broker

Example Request
curl "https://api.example.org/v3/service_brokers" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_service_broker",
    "url": "https://example.service-broker.com",
    "credentials": {
      "type": "basic",
      "data": {
        "username": "us3rn4me",
        "password": "p4ssw0rd"
      }
    },
    "relationships": {
      "space": {
        "data": {
          "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
        }
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "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": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "space": {
      "href": "https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    }
  }
}

This endpoint creates a new service broker.

Definition

POST /v3/service_brokers

Required parameters

Name Type Description
name string Name of the service broker.
url string URL of the service broker.
credentials credentials Credentials used to authenticate against the service broker.

Optional parameters

Name Type Description Default
space to-one relationship If set, restricts broker visibility to the specified space. null

The credentials object

Name Type Description
type string Type of the authentication mechanisms that can be used. Valid value is basic.
data object Data is used to hold the actual credentials depending on the authentication mechanism.
Example basic credentials
{
  "type": "basic",
  "data": {
    "username": "admin",
    "password": "secretpassw0rd"
  }
}
Basic credentials data
Name Type Description
username string The username with which to authenticate against the service broker.
password string The password with which to authenticate against the service broker.

Permitted roles

Space Developer
Admin

Sidecars

Sidecars are additional operating system processes that are run in the same container as a process.

Use cases for sidecars

Sidecars are useful for any app processes that need to communicate with another within the same container or are otherwise dependent on each other. Some use cases are:

Steps to create a sidecar

The recommended way to create sidecars for your app is with an app manifest.

 sidecars:
  - name: authenticator
    process_types: [ 'web', 'worker' ]
    command: bundle exec run-authenticator
  - name: performance monitor
      process_types: [ 'web' ]
      command: bundle exec run-performance-monitor
      memory: 128M

1 Applies for Java apps. If you do not reserve memory for the sidecar, the JVM will consume all of the memory in the app container. This value must be less thatn the process’ reserved memory.

Current limitations

The sidecar object

Example Sidecar object
{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Name Type Description
guid uuid Unique identifier for the sidecar.
name string Human-readable name for the sidecar.
command string The command used to start the sidecar.
process_types array of strings A list of process types the sidecar applies to.
memory_in_mb integer Reserved memory for sidecar.
relationships.app to-one relationship The app the sidecare is associated with.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.

Create a sidecar associated with an app

Example Request
curl "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/sidecars" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "auth-sidecar",
    "command": "bundle exec rackup",
    "process_types": ["web", "worker"],
    "memory_in_mb": 300
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

POST /v3/apps/:guid/sidecars

Required parameters

Name Type Description
name string Human-readable name for the sidecar.
command string The command used to start the sidecar.
process_types array of strings A list of process types the sidecar applies to.

Optional parameters

Name Type Description
memory_in_mb integer Reserved memory for sidecar.

Permitted roles

Admin
Space Developer

Get a sidecar

Example Request
curl "https://api.example.org/v3/sidecars/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

GET /v3/sidecars/:guid

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Update a sidecar

Example Request
curl "https://api.example.org/v3/sidecars/[guid]" \
  -X PATCH \
  -H "Authorization: bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auth-sidecar",
    "command": "bundle exec rackup",
    "process_types": ["web", "worker"],
    "memory_in_mb": 300
  }'

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
  "name": "auth-sidecar",
  "command": "bundle exec rackup",
  "process_types": ["web", "worker"],
  "memory_in_mb": 300,
  "relationships": {
    "app": {
      "data": {
        "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
      }
    }
  },
  "created_at": "2017-02-01T01:33:58Z",
  "updated_at": "2017-02-01T01:33:58Z"
}

Definition

PATCH /v3/sidecars/:guid

Optional parameters

Name Type Description
name string Human-readable name for the sidecar.
command string The command used to start the sidecar.
process_types array of strings A list of process types the sidecar applies to.
memory_in_mb integer Reserved memory for sidecar.

Permitted roles

Admin
Space Developer

List sidecars for app

Example Request
curl "https://api.example.org/v3/apps/[guid]/sidecars" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "name": "auth-sidecar",
      "command": "bundle exec rackup",
      "process_types": ["web", "worker"],
      "memory_in_mb": 300,
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z"
    },
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
      "name": "echo-sidecar",
      "command": "start-echo-server",
      "process_types": ["web"],
      "memory_in_mb": 300,
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:59Z",
      "updated_at": "2017-02-01T01:33:59Z"
    }
  ]
}

Retrieves all sidecars associated with a app.

Definition

GET /v3/apps/:guid/sidecars

Query parameters

Name Type Description
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

List sidecars for process

Example Request
curl "https://api.example.org/v3/processes/[guid]/sidecars" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41920",
      "name": "auth-sidecar",
      "command": "bundle exec rackup",
      "process_types": ["web", "worker"],
      "memory_in_mb": 300,
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:58Z",
      "updated_at": "2017-02-01T01:33:58Z"
    },
    {
      "guid": "885735b5-aea4-4cf5-8e44-961af0e41921",
      "name": "echo-sidecar",
      "command": "start-echo-server",
      "process_types": ["web"],
      "memory_in_mb": 300,
      "relationships": {
        "app": {
          "data": {
            "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446"
          }
        }
      },
      "created_at": "2017-02-01T01:33:59Z",
      "updated_at": "2017-02-01T01:33:59Z"
    }
  ]
}

Retrieves all sidecars associated with a process.

Definition

GET /v3/processes/:guid/sidecars

Query parameters

Name Type Description
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.
order_by string Value to sort by. Defaults to ascending. Prepend with - to sort descending.
Valid values are created_at, updated_at.

Permitted roles

Admin
Admin Read-Only
Global Auditor
Org Manager
Space Auditor
Space Developer
Space Manager

Delete a sidecar

Example Request
curl "https://api.example.org/v3/sidecars/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 204 No Content

Definition

DELETE /v3/sidecars/:guid

Permitted roles

Admin
Space Developer

Space Manifest

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

The space manifest specification

Example Manifest
---
applications:
- name: app1
  buildpacks:
  - ruby_buildpack
  - java_buildpack
  env:
    VAR1: value1
    VAR2: value2
  routes:
  - route: route.example.com
  - route: another-route.example.com
  services:
  - my-service1
  - my-service2
  - name: my-service-with-arbitrary-params
    parameters:
      key1: value1
      key2: value2
  stack: cflinuxfs3
  metadata:
    annotations:
      contact: "[email protected] [email protected]"
    labels:
      sensitive: true
  processes:
  - type: web
    command: start-web.sh
    disk_quota: 512M
    health-check-http-endpoint: /healthcheck
    health-check-type: http
    health-check-invocation-timeout: 10
    instances: 3
    memory: 500M
    timeout: 10
  - type: worker
    command: start-worker.sh
    disk_quota: 1G
    health-check-type: process
    instances: 2
    memory: 256M
    timeout: 15
- name: app2
  env:
    VAR1: value1
  processes:
  - type: web
    instances: 1
    memory: 256M
  sidecars:
  - name: authenticator
    process_types: [ 'web', 'worker' ]
    command: bundle exec run-authenticator
    memory: 800M

  - name: upcaser
    process_types: [ 'worker' ]
    command: ./tr-server
    memory: 2G

Space-level configuration

Field Description
applications An array of App configurations

App-level configuration

This configuration is specified at the top-level and applies to all of the app’s processes.

Field Description
buildpacks Must be an Array.
a) An empty array, which will automatically select the appropriate default buildpack according to the coding language.
b) An array of one or more URLs pointing to buildpacks.
c) An array of one or more installed buildpack names.
Replaces the legacy buildpack field.
docker If present, the created app will have Docker lifecycle type. The value of this key is ignored by the API but may be used by clients to source the registry address of the image and credentials, if needed. The generate manifest endpoint will return the registry address of the image and username provided with this key.
env A key-value hash of environment variables to be used for the app when running.
no-route Boolean value. Removes the app’s routes if true; ignored if false. Cannot be used in conjunction with the routes attribute when set to true.
processes List of configurations for individual process types. See Process-level configuration.
random-route Boolean value. Creates a random route for the app if true; ignored if false, if routes is specified, if the app already has routes, or if no-route is specified.
routes An array of route hashes declaring HTTP and TCP routes to be mapped to the app. Each route is created if it does not already exist. Example route hash entry: - route: www.example.com/path
services An array of service-instances to bind to the app. See Service-level configuration.
sidecars An array of configurations for individual sidecars. See Sidecar-level configuration.
stack The root filesystem to use with the buildpack, for example cflinuxfs3.
metadata.labels (experimental) Labels applied to the app.
metadata.annotations (experimental) Annotations applied to the app.
buildpack DEPRECATED in favor of the buildpacks field above.
a) Blank OR default OR null will automatically select the appropriate default buildpack according to the coding language.
b) A URL pointing to a buildpack.
c) Name of an installed buildpack.

Process-level configuration

This configuration is for the individual process. Each process is created if it does not already exist.

With the exception of type, process-level fields can also be provided at the top-level and will apply to the web process only.

If there is a process with type: web defined in the processes section, then all top level process configuration will be ignored.

Field Description
type (Required) Process type. The identifier for the processes to be configured.
command The command used to start the process. This overrides start commands from Procfiles and buildpacks.
disk_quota The disk limit for all instances of the web process.
This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
health-check-http-endpoint Endpoint called to determine if the app is healthy.
health-check-invocation-timeout The timeout in seconds for individual health check requests for http and port health checks.
health-check-type Type of health check to perform. none is deprecated and an alias to process.
instances The number of instances to run.
memory The memory limit for all instances of the web process.
This attribute requires a unit of measurement: B, K, KB, M, MB, G, GB, T, or TB in upper case or lower case.
timeout Time in seconds at which the health-check will report failure.

Service-level configuration

This configuration is creating new service bindings between the app and a service instance. The services field can take either an array of service instance name strings or an array of the following service-level fields.

Field Description
name (Required) Service instance name. The name of the service instance to be bound to.
parameters A map of arbitrary key/value pairs to send to the service broker during binding.

Sidecar-level configuration

This configuration is for the individual sidecar. Each sidecar is created if it does not already exist.

Field Description
name (Required) Sidecar name. The identifier for the sidecars to be configured.
command The command used to start the sidecar.
process_types List of processes to associate sidecar with.
memory Memory in mb that the sidecar will be allocated.

Apply a space manifest

Example Request
curl "https://api.example.org/v3/spaces/[guid]/actions/apply_manifest" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/x-yaml" \
  --data-binary @/path/to/manifest.yml
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Apply changes specified in a manifest to the named apps and their underlying processes. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, routes, or services.

Definition

POST /v3/spaces/:guid/actions/apply_manifest

Query parameters

Name Type Description
no_route boolean Unmaps all existing routes and blocks route creation for apps in the manifest.

Permitted roles

Admin
Space Developer

Users

Every Cloud Foundry action (pushing an application, creating a space) requires a user. Each Cloud Foundry installation has one pre-installed user, admin, which can create subsequent users. Users can be assigned roles which give them privileges to perform actions. For example, the Space Developer role grants a user permission to manage apps and services in a space (to push apps, scale apps, delete apps).

The user object

Example User object
  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Name Type Description
guid uuid Unique identifier for the user.
created_at datetime The time with zone when the object was created.
updated_at datetime The time with zone when the object was last updated.
username string The name registered in UAA. Will be null for UAA clients and non-UAA users.
presentation_name string The name displayed for the user. For UAA users, this is the same as the username. For UAA clients, this is the UAA client ID.
origin string The identity provider for the UAA user. Will be null for UAA clients.
links links object Links to related resources.

Create a user

Creating a user requires one value, a GUID. This creates a user in the Cloud Controller database.

Generally, the GUID should match the GUID of an already-created user in the UAA database, though this is not required.

Example Request
curl "https://api.example.org/v3/users" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
  }'
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

POST /v3/users

Required parameters

Name Type Description
guid string Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user’s GUID. In the case of UAA clients, this will match the UAA client ID.

Permitted roles

Role Notes
Admin

List users

Example Request
curl "https://api.example.org/v3/users" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/users?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/users?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/users?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
     {
      "guid": "client_id",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "username": null,
      "presentation_name": "client_id",
      "origin": null,
      "links": {
        "self": {
          "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
        }
      }
    },
    {
      "guid": "9da93b89-3f89-4f05-7238-8a2b123c79l9",
      "created_at": "2019-03-08T01:06:19Z",
      "updated_at": "2019-03-08T01:06:19Z",
      "username": "some-name",
      "presentation_name": "some-name",
      "origin": "uaa",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9"
        }
      }
    }
  ]
}


Retrieve all users that the current user can see. For users without the admin or admin_read_only roles, this will just return the current user.

Definition

GET /v3/users

Query parameters

Name Type Description
page integer Page to display. Valid values are integers >= 1.
per_page integer Number of results per page.
Valid values are 1 through 5000.

Permitted roles

All Roles

Get a user

Example Request
curl "https://api.example.org/v3/users/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

  {
    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
    "created_at": "2019-03-08T01:06:19Z",
    "updated_at": "2019-03-08T01:06:19Z",
    "username": "some-name",
    "presentation_name": "some-name",
    "origin": "uaa",
    "links": {
      "self": {
        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
      }
    }
  }

Definition

GET /v3/users/:guid

Permitted roles

Admin
Admin Read-Only

Note: A user can always see themselves with this endpoint, regardless of role.

Delete a user

Example Request
curl "https://api.example.org/v3/users/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
Location: https://api.example.org/v3/jobs/[guid]

Definition

DELETE /v3/users/:guid

Permitted roles

Role Notes
Admin