NAV
curl

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

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

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.

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.

Name Type Description
href string The absolute URL.
method string An optional field containing the HTTP method to be used when following the URL.

Relationships

Relationships represent associations between resources. Relationships can be used to create, read, update, and delete associations through the relationship sub resource.

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 object 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]"

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.

Pagination

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

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

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

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 cflinuxfs2

Docker lifecycle

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

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.

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

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.
space (experimental) to-one relationship The space the app is contained in.
links links object Links to related resources.

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": "cflinuxfs2"
    }
  },
  "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"
    },
    "route_mappings": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "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"
    }
  }
}

Definition

POST /v3/apps

Required Parameters

Name Type Description
name string Name of the app.
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

Permitted Roles

Space Developer
Admin

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": "cflinuxfs2"
    }
  },
  "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"
    },
    "route_mappings": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "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"
    }
  }
}

Definition

GET /v3/apps/:guid

Permitted Roles

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

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": "cflinuxfs2"
    }
  },
  "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"
    },
    "route_mappings": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "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"
    }
  }
}

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.

Permitted Roles

Space Developer
Admin

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

Space Developer
Admin
Admin Read-Only

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

Space Developer
Admin
Admin Read-Only

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

Space Developer
Admin

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

Space Developer
Admin

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

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

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"
    }
  ],
  "stack": "cflinuxfs2",
  "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"
    }
  }
}

Definition

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

Permitted Roles

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

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": "cflinuxfs2"
    }
  },
  "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"
    },
    "route_mappings": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "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"
    }
  }
}

Definition

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

Permitted Roles

Space Developer
Admin

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": "cflinuxfs2"
    }
  },
  "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"
    },
    "route_mappings": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "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"
    }
  }
}

Definition

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

Permitted Roles

Space Developer
Admin

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

Space Developer
Admin

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": "cflinuxfs2"
        }
      },
      "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"
        },
        "route_mappings": {
          "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
        },
        "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"
        }
      }
    },
    {
      "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": "cflinuxfs2"
        }
      },
      "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"
        },
        "route_mappings": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/route_mappings"
        },
        "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"
        }
      }
    }
  ]
}

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

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

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.

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": "bill@example.com"
  },
  "state": "STAGING",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs2"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": null,
  "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

Permitted Roles

Space Developer
Admin

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": "bill@example.com"
  },
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": "cflinuxfs2"
    }
  },
  "package": {
    "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
  },
  "droplet": {
    "guid": "1e1186e7-d803-4c46-b9d6-5c81e50fe55a"
  },
  "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

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

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": "bill@example.com"
      },
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": "cflinuxfs2"
        }
      },
      "package": {
        "guid": "8e4da443-f255-499c-8b47-b3729b5b7432"
      },
      "droplet": null,
      "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.
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.

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

Name Type Description
state string State of the droplet. Valid states are 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.

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 cflinuxfs2
Detected buildpack object
Name Type Description
name string Buildpack name
detect_output string Output during buildpack detect process

Docker droplet

Name Type Description
image string Docker image name.

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

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
app to-one relationship A relationship to the destination app.

Permitted Roles

Space Developer
Admin

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"
    }
  ],
  "stack": "cflinuxfs2",
  "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"
    }
  }
}

Definition

GET /v3/droplets/:guid

Permitted Roles

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

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

Space Developer
Admin

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"
        }
      ],
      "stack": "cflinuxfs2",
      "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"
        }
      }
    },
    {
      "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"
        }
      }
    }
  ]
}

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.

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"
        }
      ],
      "stack": "cflinuxfs2",
      "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"
        }
      }
    },
    {
      "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"
        }
      }
    }
  ]
}

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.

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"
        }
      ],
      "stack": "cflinuxfs2",
      "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"
        }
      }
    },
    {
      "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"
        }
      }
    }
  ]
}

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.

Isolation Segments

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

The isolation_segment object

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.

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

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.

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

Definition

GET /v3/isolation_segments/:guid

Permitted Roles

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

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

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.

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

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

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.

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

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

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

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

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

Jobs

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

The job object

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

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

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

Name Type Description
name string Name of the organization.
guid uuid Unique identifier for 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.

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",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
    }
  }
}

Definition

POST /v3/organizations

Required Parameters

Name Type Description
name string Organization name

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.

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",
      "links": {}
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
      "created_at": "2017-02-02T00:14:30Z",
      "updated_at": "2017-02-02T00:14:30Z",
      "name": "org2",
      "links": {}
    }
  ]
}

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

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",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/organizations/24637893-3b77-489d-bb79-8466f0d88b52"
    }
  }
}

This endpoint retrieves the specified organization object.

Definition

GET /v3/organizations/:guid

Permitted Roles

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

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",
      "links": {}
    },
    {
      "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
      "created_at": "2017-02-02T00:14:30Z",
      "updated_at": "2017-02-02T00:14:30Z",
      "name": "org2",
      "links": {}
    }
  ]
}

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

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

Org Manager
Admin

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

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

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

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.

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.

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.

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": "PROCESSING_UPLOAD",
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "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"
    }
  }
}

Definition

POST /v3/packages

Required Parameters

Name Type Description
type string Type of the package. Valid values are bits, docker.
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.

Permitted Roles

Space Developer
Admin

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",
  "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

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

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" \
  -F bits=@"package.zip" \
  -X POST \
  -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",
  "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"
    }
  }
}

Upload file for a package of type bits. The file must be sent as part of a multi-part form.

Definition

POST /v3/packages/:guid/upload

Required Parameters

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

Permitted Roles

Space Developer
Admin

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

Space Developer
Admin

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

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
app to-one relationship A relationship to the destination app.

Permitted Roles

Space Developer
Admin

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

Space Developer
Admin

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

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.

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

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.

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

Name Type Description
type string Process type. A unique identifier for processes belonging to an app.
command string The command is used to start the process.
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.
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.

The health_check object

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 the health check can fail before the process is restarted.
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

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.

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

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

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

Definition

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

Permitted Roles

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

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" }'
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
    }
  },
  "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 The command is used to start the process.
health_check health_check object The health check to perform on the process.

Permitted Roles

Space Developer
Admin

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

Space Developer
Admin

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

Space Developer
Admin

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
        }
      },
      "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
        }
      },
      "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.

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
        }
      },
      "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
        }
      },
      "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.

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

Name Type Description
name string Name of the space.
guid uuid Unique identifier for 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.
organization (experimental) to-one relationship The organization the space is contained in.
links links object Links to related resources.

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

Definition

POST /v3/spaces

Required Parameters

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

Permitted Roles

Admin
OrgManager

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

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

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

This endpoint retrieves the specified space object.

Definition

GET /v3/spaces/:guid

Permitted Roles

Admin
Space Developer
Read-Only Admin
Global Auditor
Space Manager
Space Auditor
Org 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

Org Manager
Admin

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

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

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

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.

Create a task

Example Request
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 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",
  "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/:app_guid/tasks

Required Parameters

Name Type Description
command string Command that will be executed

Optional Parameters

Name Type Description Default
name string Name of the task. auto-generated
disk_in_mb integer Amount of disk to allocate for the task in MB. operator-configured default_app_disk_in_mb
memory_in_mb 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

Allowed Roles

Space Developer
Admin

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",
  "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

Allowed Roles

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

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",
  "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/:task_guid/actions/cancel
PUT /v3/tasks/:task_guid/cancel (Deprecated)

Allowed Roles

Space Developer
Admin

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",
      "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",
      "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.

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",
      "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",
      "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.

Experimental Resources

App Features

The app feature object

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.

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

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

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.

Allowed Roles

Space Developer
Admin

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

App Manifest

The app manifest

Field Description
buildpack 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.
command The command used to start the process.
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.
env A key-value hash of environment variables to be used for the app when running.
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.
stack The root filesystem to use with the buildpack, for example cflinuxfs2.

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]

Definition

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

Allowed Roles

Space Developer
Admin

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": "cflinuxfs2"
    }
  },
  "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"
    },
    "route_mappings": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "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"
    }
  }
}

Definition

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

Permitted Roles

Space Developer
Admin

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

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

Route Mappings

Route Mappings are relations between an app and a route; to direct traffic from a route to an app, you must first create a mapping.

The route_mapping object

Name Type Description
guid uuid Unique identifier for the route mapping.
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 route mapping

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

{
  "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
  "created_at": "2016-02-17T01:50:05Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "route": {
      "href": "https://api.example.org/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
    },
    "process": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
    }
  }
}

Definition

POST /v3/route_mappings

Required Parameters

Name Type Description
app to-one relationship A relationship to an app.
route to-one relationship A relationship to a route.

Optional Parameters

Name Type Description Default
process to-one relationship A relationship to a process. This relationship is specified by type instead of guid.

Permitted Roles

Space Developer
Admin

Get a route mapping

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

{
  "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
  "created_at": "2016-02-17T01:50:05Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "route": {
      "href": "https://api.example.org/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
    },
    "process": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
    }
  }
}

Definition

GET /v3/route_mappings/:guid

Permitted Roles

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

Delete a route mapping

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

Definition

DELETE /v3/route_mappings/:guid

Permitted Roles

Space Developer
Admin

List route mappings

Example Request
curl "https://api.example.org/v3/route_mappings" \
  -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/route_mappings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/route_mappings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/route_mappings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
      "created_at": "2016-02-17T01:50:05Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "route": {
          "href": "https://api.example.org/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
        },
        "process": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
        }
      }
    },
    {
      "guid": "9f4970a8-9e6f-4984-b0a5-5e4a8af91665",
      "created_at": "2016-02-17T01:50:05Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/route_mappings/9f4970a8-9e6f-4984-b0a5-5e4a8af91665"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "route": {
          "href": "https://api.example.org/v2/routes/a32332f0-fb30-4e9e-9b78-348b8b6b98b6"
        },
        "process": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/admin-web"
        }
      }
    }
  ]
}

Retrieve all route mappings the user has access to.

Definition

GET /v3/route_mappings

Query Parameters

Name Type Description
app_guids list of strings Comma-delimited list of app guids to filter by.
route_guids list of strings Comma-delimited list of route 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.

List route mappings for an app

Example Request
curl "https://api.example.org/v3/apps/[guid]/route_mappings" \
  -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/route_mappings?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/route_mappings?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/route_mappings?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
      "created_at": "2016-02-17T01:50:05Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "route": {
          "href": "https://api.example.org/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
        },
        "process": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
        }
      }
    },
    {
      "guid": "9f4970a8-9e6f-4984-b0a5-5e4a8af91665",
      "created_at": "2016-02-17T01:50:05Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/route_mappings/9f4970a8-9e6f-4984-b0a5-5e4a8af91665"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "route": {
          "href": "https://api.example.org/v2/routes/a32332f0-fb30-4e9e-9b78-348b8b6b98b6"
        },
        "process": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/admin-web"
        }
      }
    }
  ]
}

Retrieve route mappings for an app.

Definition

GET /v3/apps/:guid/route_mappings

Query Parameters

Name Type Description
route_guids list of strings Comma-delimited list of route 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.

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

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.
app to-one relationship A relationship to an app.
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

Space Developer
Admin

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

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

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

Space Developer
Admin

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.

Service Instances

An instantiation of a service offering.

The service_instance object

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.
space to-one relationship The space the service instance is contained in.
links links object Links to related resources.

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"
          }
        }
      },
      "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.

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

Space Developer
Admin

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

Space Developer
Admin

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
Space Developer
Space Manager
Space Auditor
Org Manager