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
SpaceManager This role provides Space management access
SpaceDeveloper This role allows developers to create and manage apps and services in a Space
SpaceAuditor This role allows 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.

Resources

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.

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

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.

Relationships

Relationships allow users to create, read, update, and delete associations between resources. Relationships are managed through a 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.

To-One relationships

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

Setting the 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": {
        "guid": "publisher-guid"
      }
    }
  }'

To-Many relationships

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

Adding related 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 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 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 relationships
curl "https://api.example.org/v3/books/[guid]/relationships/authors/[author-guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Errors

The error object

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

Example Error
HTTP/1.1 422 Unprocessable

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

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

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

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

Create a task

Definition
POST /v3/apps/:guid/tasks HTTP/1.1
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
{
  "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"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

This endpoint creates a new task.

Body Parameters

Get a task

Definition
GET /v3/tasks/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/tasks/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

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

Body Parameters

No arguments

Cancel a task

Definition
PUT /v3/tasks/:task_guid/cancel HTTP/1.1
Example Request
curl "https://api.example.org/v3/tasks/[guid]/cancel" \
  -X PUT \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 202 Accepted
{
  "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"
    },
    "droplet": {
      "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

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

Body Parameters

No arguments

List tasks

Definition
GET /v3/tasks HTTP/1.1
Example Request
curl "https://api.example.org/v3/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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"
        },
        "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"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    }
  ]
}

This endpoint retrieves the tasks the user has access to. The command field is excluded in the response.

Query Parameters

List tasks for an app

Definition
GET /v3/apps/:guid/tasks HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/:guid/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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"
        },
        "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"
        },
        "droplet": {
          "href": "https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    }
  ]
}

This endpoint retrieves the tasks the user has access to. The command field may be excluded in the response based on the user’s role.

Query Parameters

Experimental 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

Create an app

Definition
POST /v3/apps HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "name": "my_app",
    "environment_variables": {
      "HTTP_PROXY": "http://proxy.example.com"
    },
    "lifecycle": {
      "type": "buildpack",
      "data": {
        "buildpacks": ["java_buildpack"]
      }
    },
    "relationships": {
      "space": {
        "guid": "2f35885d-0c9d-4423-83ad-fd05066f8576"
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "desired_state": "STOPPED",
  "total_desired_instances": 0,
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs2"
    }
  },
  "environment_variables": {
    "HTTP_PROXY": "http://proxy.example.com"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v2/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"
    },
    "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/start",
      "method": "PUT"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
      "method": "PUT"
    }
  }
}

This endpoint creates a new app.

Body Parameters

Get an app

Definition
GET /v3/apps/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "desired_state": "STOPPED",
  "total_desired_instances": 0,
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs2"
    }
  },
  "environment_variables": {
    "HTTP_PROXY": "http://proxy.example.com"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v2/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"
    },
    "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/start",
      "method": "PUT"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
      "method": "PUT"
    }
  }
}

This endpoint retrieves an app.

Get environment for an app

Definition
GET /v3/apps/:guid/env HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/env" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "staging_env_json": {
    "GEM_CACHE": "http://gem-cache.example.com"
  },
  "running_env_json": {
    "HTTP_PROXY": "http://proxy.example.com"
  },
  "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.com/drain",
          "provider": null
        }
      ]
    }
  },
  "application_env_json": {
    "VCAP_APPLICATION": {
      "limits": {
        "fds": 16384
      },
      "application_name": "my_app",
      "application_uris": [ "my_app.example.com" ],
      "name": "my_app",
      "space_name": "my_space",
      "space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
      "uris": [ "my_app.example.com" ],
      "users": null
    }
  }
}

This endpoint retrieves the environment variables that will be provided to an app at runtime. It will include environment variables for Environment Variable Groups and Service Bindings.

Update an app

Definition
PATCH /v3/apps/:guid HTTP/1.1
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",
    "environment_variables": {
      "HTTP_PROXY": "http://proxy.example.com"
    },
    "lifecycle": {
      "type": "buildpack",
      "data": {
        "buildpacks": ["java_buildpack"],
      }
    }
  }' 
Example Response
HTTP/1.1 200 OK
{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "desired_state": "STARTED",
  "total_desired_instances": 3,
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-03-18T11:32:30Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs2"
    }
  },
  "environment_variables": {
    "HTTP_PROXY": "http://proxy.example.com"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v2/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"
    },
    "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/start",
      "method": "PUT"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
      "method": "PUT"
    }
  }
}

This endpoint updates an app.

Body Parameters

Set current droplet for an app

Definition
PUT /v3/apps/:guid/droplets/current HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/droplets/current" \
  -X PUT \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{ "droplet_guid": "[droplet_guid]" }'
Example Response
HTTP/1.1 200 OK
{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": null
    }
  },
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 4096,
  "result": {
    "execution_metadata": "",
    "process_types": {
      "rake": "bundle exec rake",
      "web": "bundle exec rackup config.ru -p $PORT"
    },
    "hash": {
      "type": "sha256",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    },
    "buildpacks": [
      {
        "name": "ruby_buildpack",
        "detect_output": "ruby 1.6.14"
      }
    ],
    "stack": "cflinuxfs2"
  },
  "environment_variables": {
    "CF_STACK": "cflinuxfs2",
    "VCAP_APPLICATION": {
      "limits": {
        "mem": 1024,
        "disk": 4096,
        "fds": 16384
      },
      "application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
      "application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "application_name": "my_app",
      "application_uris": [
        "my_app.example.com"
      ],
      "version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "name": "my_app",
      "space_name": "my_space",
      "space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
      "uris": [
        "my_app.example.com"
      ],
      "users": null
    },
    "MEMORY_LIMIT": "1024m",
    "VCAP_SERVICES": {}
  },
  "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/droplets/current",
      "method": "PUT"
    }
  }
}

This endpoint sets the current droplet for an app. The current droplet is the droplet that the app will use when running.

Get current droplet for an app

Definition
GET /v3/apps/:guid/droplets/current HTTP/1.1
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
{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": null
    }
  },
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 4096,
  "result": {
    "execution_metadata": "",
    "process_types": {
      "rake": "bundle exec rake",
      "web": "bundle exec rackup config.ru -p $PORT"
    },
    "hash": {
      "type": "sha256",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    },
    "buildpacks": [
      {
        "name": "ruby_buildpack",
        "detect_output": "ruby 1.6.14"
      }
    ],
    "stack": "cflinuxfs2"
  },
  "environment_variables": {
    "CF_STACK": "cflinuxfs2",
    "VCAP_APPLICATION": {
      "limits": {
        "mem": 1024,
        "disk": 4096,
        "fds": 16384
      },
      "application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
      "application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "application_name": "my_app",
      "application_uris": [
        "my_app.example.com"
      ],
      "version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "name": "my_app",
      "space_name": "my_space",
      "space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
      "uris": [
        "my_app.example.com"
      ],
      "users": null
    },
    "MEMORY_LIMIT": "1024m",
    "VCAP_SERVICES": {}
  },
  "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/droplets/current",
      "method": "PUT"
    }
  }
}

This endpoint retrieves the current droplet for an app.

Body Parameters

No arguments

Start an app

Definition
PUT /v3/apps/:guid/start HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/start" \
  -X PUT \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "desired_state": "STARTED",
  "total_desired_instances": 3,
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-03-18T11:32:30Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs2"
    }
  },
  "environment_variables": {
    "HTTP_PROXY": "http://proxy.example.com"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v2/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"
    },
    "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/start",
      "method": "PUT"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
      "method": "PUT"
    }
  }
}

This endpoint starts running the app.

Stop an app

Definition
PUT /v3/apps/:guid/stop HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/stop" \
  -X PUT \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "desired_state": "STOPPED",
  "total_desired_instances": 3,
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-03-18T11:32:30Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": ["java_buildpack"],
      "stack": "cflinuxfs2"
    }
  },
  "environment_variables": {
    "HTTP_PROXY": "http://proxy.example.com"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v2/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"
    },
    "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/start",
      "method": "PUT"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
      "method": "PUT"
    }
  }
}

This endpoint stops a running app.

Delete an app

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

This endpoint deletes an app.

List apps

Definition
GET /v3/apps HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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",
      "desired_state": "STARTED",
      "total_desired_instances": 3,
      "created_at": "2016-03-17T21:41:30Z",
      "updated_at": "2016-03-18T11:32:30Z",
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": ["java_buildpack"],
          "stack": "cflinuxfs2"
        }
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
        },
        "space": {
          "href": "https://api.example.org/v2/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"
        },
        "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/start",
          "method": "PUT"
        },
        "stop": {
          "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
          "method": "PUT"
        }
      }
    },
    {
      "guid": "02b4ec9b-94c7-4468-9c23-4e906191a0f8",
      "name": "my_app2",
      "desired_state": "STOPPED",
      "total_desired_instances": 0,
      "created_at": "1970-01-01T00:00:02Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpacks": ["ruby_buildpack"],
          "stack": "cflinuxfs2"
        }
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
        },
        "space": {
          "href": "https://api.example.org/v2/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"
        },
        "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/start",
          "method": "PUT"
        },
        "stop": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/stop",
          "method": "PUT"
        }
      }
    }
  ]
}

This endpoint retrieves all the apps the user has access to.

Query Parameters

Droplets

Droplets are created by 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 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

The lifecycle object

Lifecycle objects describe buildpacks or docker images.

Lifecycle object for buildpack droplets

Lifecycle object for docker

Droplets created with a docker lifecycle are only valid for docker packages.

Create a droplet

Definition
POST /v3/packages/:guid/droplets HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages/[guid]/droplets" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "environment_variables": {
      "CUSTOM_ENV_VAR": "hello"
    },
    "lifecycle": {
      "type": "buildpack",
      "data": {
        "buildpacks": ["http://github.com/myorg/awesome-buildpack"],
        "stack": "cflinuxfs2"
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "STAGING",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": null
    }
  },
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 4096,
  "result": null,
  "environment_variables": {
    "CF_STACK": "cflinuxfs2",
    "VCAP_APPLICATION": {
      "limits": {
        "mem": 1024,
        "disk": 4096,
        "fds": 16384
      },
      "application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
      "application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "application_name": "my_app",
      "application_uris": [
        "my_app.example.com"
      ],
      "version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "name": "my_app",
      "space_name": "my_space",
      "space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
      "uris": [
        "my_app.example.com"
      ],
      "users": null
    },
    "MEMORY_LIMIT": "1024m",
    "VCAP_SERVICES": {}
  },
  "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/droplets/current",
      "method": "PUT"
    }
  }
}

This endpoint creates a new droplet from a package.

Body Parameters

Copy a droplet

Definition
POST /v3/droplets/:guid/copy HTTP/1.1
Example Request
curl "https://api.example.org/v3/droplets/[guid]/copy" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "relationships": {
      "app": {
        "guid": "[app-guid]"
      }
    }
  }'
Example Response
HTTP/1.1 201 Created
{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "COPYING",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": null
    }
  },
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 4096,
  "result": null,
  "environment_variables": {},
  "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/droplets/current",
      "method": "PUT"
    }
  }
}

This endpoint copies a droplet to a different app. The copied droplet excludes the environment variables listed on the source droplet.

Query Parameters

Get a droplet

Definition
GET /v3/droplets/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/droplets/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpacks": [ "ruby_buildpack" ],
      "stack": null
    }
  },
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 4096,
  "result": {
    "execution_metadata": "",
    "process_types": {
      "rake": "bundle exec rake",
      "web": "bundle exec rackup config.ru -p $PORT"
    },
    "hash": {
      "type": "sha256",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    },
    "buildpacks": [
      {
        "name": "ruby_buildpack",
        "detect_output": "ruby 1.6.14"
      }
    ],
    "stack": "cflinuxfs2"
  },
  "environment_variables": {
    "CF_STACK": "cflinuxfs2",
    "VCAP_APPLICATION": {
      "limits": {
        "mem": 1024,
        "disk": 4096,
        "fds": 16384
      },
      "application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
      "application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "application_name": "my_app",
      "application_uris": [
        "my_app.example.com"
      ],
      "version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "name": "my_app",
      "space_name": "my_space",
      "space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
      "uris": [
        "my_app.example.com"
      ],
      "users": null
    },
    "MEMORY_LIMIT": "1024m",
    "VCAP_SERVICES": {}
  },
  "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/droplets/current",
      "method": "PUT"
    }
  }
}

This endpoint retrieves a specific droplet.

Body Parameters

No arguments

Delete a droplet

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

This endpoint deletes a specific droplet.

Body Parameters

No arguments

List droplets

Definition
GET /v3/droplets HTTP/1.1
Example Request
curl "https://api.example.org/v3/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": null
        }
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": {
        "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
        "process_types": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "hash": {
          "type": "sha256",
          "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        },
        "buildpacks": [
          {
            "name": "ruby_buildpack",
            "detect_output": "ruby 1.6.14"
          }
        ],
        "stack": "cflinuxfs2"
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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/droplets/current",
          "method": "PUT"
        }
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": null,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

This endpoint retrieves the droplets the user has access to.

Query Parameters

List droplets for an app

Definition
GET /v3/apps/:guid/droplets HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": null
        }
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": {
        "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
        "process_types": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "hash": {
          "type": "sha256",
          "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        },
        "buildpacks": [
          {
            "name": "ruby_buildpack",
            "detect_output": "ruby 1.6.14"
          }
        ],
        "stack": "cflinuxfs2"
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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/droplets/current",
          "method": "PUT"
        }
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": null,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

This endpoint retrieves a list of droplets belonging to an app.

Body Parameters

List droplets for a package

Definition
GET /v3/packages/:guid/droplets HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages/[guid]/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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": {
          "buildpacks": [ "ruby_buildpack" ],
          "stack": null
        }
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": {
        "execution_metadata": "[PRIVATE DATA HIDDEN IN LISTS]",
        "process_types": {
          "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
        },
        "hash": {
          "type": "sha256",
          "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        },
        "buildpacks": [
          {
            "name": "ruby_buildpack",
            "detect_output": "ruby 1.6.14"
          }
        ],
        "stack": "cflinuxfs2"
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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/droplets/current",
          "method": "PUT"
        }
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": null,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

This endpoint retrieves a list of droplets belonging to a package.

Body Parameters

Isolation Segments

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

The isolation_segment object

Create an isolation segment

Definition
POST /v3/isolation_segments HTTP/1.1
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
{
   "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"
      }
   }
}

This endpoint creates a new isolation segment. Only Admins can create isolation segments.

Body Parameters

Get an isolation segment

Definition
GET /v3/isolation_segments/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
   "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"
      }
   }
}

This endpoint retrieves an isolation segment.

Update an isolation segment

Definition
PATCH /v3/isolation_segments/:guid HTTP/1.1
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
{
   "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"
      }
   }
}

This endpoint updates an isolation_segment. Only Admins can update isolation segments.

Body Parameters

Delete an isolation segment

Definition
DELETE /v3/isolation_segments/:guid HTTP/1.1
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

This endpoint deletes an isolation segment. An isolation segment cannot be deleted if it is still in the allowed list for any organization. Only Admins can delete isolation segments.

List isolation segments

Definition
GET /v3/isolation_segments HTTP/1.1
Example Request
curl "https://api.example.org/v3/isolation_segments" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
   "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"
            }
         }
      }
   ]
}

This endpoint retrieves all the 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.

Query Parameters

Entitle one or more organizations for an isolation segment

Definition
POST /v3/isolation_segments/:guid/relationships/organizations HTTP/1.1
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
{
  "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. Only Admins can entitle organizations for isolation segments. 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.

Body Parameters

Revoke entitlement to isolation segment for an organization

Definition
DELETE /v3/isolation_segments/:guid/relationships/organizations/:org_guid HTTP/1.1
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. Only Admins can revoke isolation segment entitlements. 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.

List organizations relationship

Definition
GET /v3/isolation_segments/:guid/relationships/organizations HTTP/1.1
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
{
  "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.

List spaces relationship

Definition
GET /v3/isolation_segments/:guid/relationships/spaces HTTP/1.1
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
{
  "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.

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

List organizations

Definition
GET /v3/organizations HTTP/1.1
Example Request
curl "https://api.example.org/v3/organizations" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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": {}
    }
  ]
}

This endpoint retrieves the organizations the user has access to.

Query Parameters

List organizations for isolation segment

Definition
GET /v3/isolation_segments/:guid/organizations HTTP/1.1
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
{
  "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": {}
    }
  ]
}

This endpoint retrieves the organizations entitled to the isolation segment. It only returns the organizations the user has access to.

Query Parameters

Assign default isolation segment

Definition
PATCH /v3/organizations/:guid/relationships/default_isolation_segment HTTP/1.1
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
{
  "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"
    }
  }
}

This endpoint sets the default isolation segment for a given organization. Only Admins and Org Managers can set the default. Only isolation segments that are entitled to the organization are eligible to be the default isolation segment.

Apps will not run in the new default isolation segment until they are restarted.

Body Parameters

Get default isolation segment

Definition
GET /v3/organizations/:guid/relationships/default_isolation_segment HTTP/1.1
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
{
  "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"
    }
  }
}

This endpoint retrieves the default isolation segment for a given organization.

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

Create a package

Definition
POST /v3/packages HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "docker",
    "relationships": {
      "app": {
        "guid": [guid]
      }
    },
    "data": {
      "image": "registry/image:latest"
    }
  }'
Example Response
HTTP/1.1 201 Created
{
  "guid": "4cb65058-f04f-458f-aca1-5f4e43de6407",
  "type": "docker",
  "data": {
    "hash": {
      "type": "sha256",
      "value": null
    },
    "error": null,
    "image": "registry/image:latest"
  },
  "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"
    }
  }
}

This endpoint creates a new package.

Body Parameters

Get a package

Definition
GET /v3/packages/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "hash": {
      "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"
    },
    "stage": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/droplets",
      "method": "POST"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

This endpoint retrieves a specific package.

Body Parameters

No arguments

Stage a package

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

Upload package bits

Definition
POST /v3/packages/:guid/upload HTTP/1.1
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
{
  "guid": "44f7c078-0934-470f-9883-4fcddc5b8f13",
  "type": "bits",
  "data": {
    "hash": {
      "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"
    },
    "stage": {
      "href": "https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/droplets",
      "method": "POST"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

This endpoint uploads bits to an existing package of type ‘bits’. The bits must be sent as part of a multi-part form

Form Parameters

Download package bits

Definition
GET /v3/packages/:guid/download HTTP/1.1
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.

Body Parameters

No arguments

Copy a Package

Definition
POST /v3/apps/:guid/packages HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/packages?source_package_guid=[guid]" \
  -X POST \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 201 Created
  {
  "guid": "fec72fc1-e453-4463-a86d-5df426f337a3",
  "type": "docker",
  "data": {
    "image": "http://awesome-sauce.com"
  },
  "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/fec72fc1-e453-4463-a86d-5df426f337a3"
    },
    "stage": {
      "href": "https://api.example.org/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3/droplets",
      "method": "POST"
    },
    "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.

Query Parameters

Delete a package

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

This endpoint deletes a specific package.

Body Parameters

No arguments

List packages

Definition
GET /v3/packages HTTP/1.1
Example Request
curl "https://api.example.org/v3/packages" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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=2&per_page=2"
    },
    "next": {
      "href": null
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "a57fd932-85db-483a-a27e-b00efbb3b0a4",
      "type": "bits",
      "data": {
        "hash": {
          "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"
        },
        "stage": {
          "href": "https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/droplets",
          "method": "POST"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
        }
      }
    },
    {
      "guid": "8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691",
      "type": "docker",
      "data": {
        "hash": {
          "type": "sha256",
          "value": null
        },
        "error": null,
        "image": "repository/docker-image:latest"
      },
      "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"
        }
      }
    }
  ]
}

This endpoint retrieves all the packages the user has access to.

Query Parameters

List packages for an app

Definition
GET /v3/apps/:guid/packages HTTP/1.1
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,
        "hash": {
          "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"
        },
        "stage": {
          "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/droplets",
          "method": "POST"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69"
        }
      }
    }
  ]
}

This endpoint retrieves the packages that associates with the given app guid.

Query Parameters

Processes

Processes define the runnable units of an app. An app can have multiple process types, each with differing commands and scale.

To configure processes for an app, a Procfile should be provided in the application source.

The process object

The health_check object

The process stats object

Get a process

Definition
GET /v3/processes/:guid HTTP/1.1
GET /v3/apps/:guid/processes/:type HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "ports": [8080],
  "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/scale",
      "method": "PUT"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

This endpoint retrieves a specific process.

Body Parameters

No arguments

Get stats for a process

Definition
GET /v3/processes/:guid/stats HTTP/1.1
GET /v3/apps/:guid/processes/:type/stats HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes/[guid]/stats" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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
    }
  ]
}

This endpoint retrieves the stats for a specific process.

Body Parameters

No arguments

Update a process

Definition
PATCH /v3/processes/:guid HTTP/1.1
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
{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "ports": [8080],
  "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/scale",
      "method": "PUT"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

This endpoint updates an existing process.

Body Parameters

Scale a process

Definition
PUT /v3/processes/:guid/scale HTTP/1.1
PUT /v3/apps/:guid/processes/:type/scale HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes/[guid]/scale" \
  -X PUT \
  -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
{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "ports": [8080],
  "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/scale",
      "method": "PUT"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

This endpoint scales an existing process.

Body Parameters

Terminate a process instance

Definition
DELETE /v3/processes/:guid/instances/:index HTTP/1.1
DELETE /v3/apps/:guid/processes/:type/instances/:index HTTP/1.1
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

This endpoint terminates 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.

Body Parameters

No arguments

List processes

Definition
GET /v3/processes HTTP/1.1
Example Request
curl "https://api.example.org/v3/processes \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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,
      "ports": [8080],
      "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/scale",
          "method": "PUT"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v2/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,
      "ports": [],
      "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/scale",
          "method": "PUT"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

This endpoint retrieves the processes the user has access to.

Query Parameters

List processes for app

Definition
GET /v3/apps/:guid/processes HTTP/1.1
Example Request
curl "https://api.example.org/v3/apps/[guid]/processes \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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,
      "ports": [8080],
      "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/scale",
          "method": "PUT"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v2/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,
      "ports": [],
      "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/scale",
          "method": "PUT"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

This endpoint retrieves the processes belonging to an app.

Query Parameters

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

Create a route mapping

Definition
POST /v3/route_mappings HTTP/1.1
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
{
  "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
  "app_port": 8080,
  "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"
    }
  }
}

This endpoint creates a new route mapping.

Body Parameters

Get a route mapping

Definition
GET /v3/route_mappings/:guid HTTP/1.1
Example Request
curl "https://api.example.org/v3/route_mappings/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "guid": "89323d4e-2e84-43e7-83e9-adbf50a20c0e",
  "app_port": 8080,
  "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"
    }
  }
}

This endpoint retrieves a specific route mapping.

Body Parameters

No arguments

Delete a route mapping

Definition
DELETE /v3/route_mappings/:guid HTTP/1.1
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

This endpoint deletes a specific route mapping.

Body Parameters

No arguments

List route mappings

Definition
GET /v3/route_mappings HTTP/1.1
Example Request
curl "https://api.example.org/v3/route_mappings" \
  -X GET \
  -H "Authorization: bearer [token]"
Example Response
HTTP/1.1 200 OK
{
  "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",
      "app_port": 8080,
      "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",
      "app_port": 8080,
      "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"
        }
      }
    }
  ]
}

This endpoint retrieves the route mappings the user has access to.

Query Parameters

List route mappings for an app

Definition
GET /v3/apps/:guid/route_mappings HTTP/1.1
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
{
  "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",
      "app_port": 8080,
      "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",
      "app_port": 8080,
      "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"
        }
      }
    }
  ]
}

This endpoint retrieves the route mappings the user has access to.

Query Parameters

  • route_guids

    optional string

    Comma-delimited list of route guids to filter by.
    Example: route_guids=route_guid1,route_guid2

  • page

    optional

    Page to display. Possible values are all integers >= 1.

  • per_page

    optional

    Number of results per page. Possible values are 1 through 5000.

  • order_by

    optional

    Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
    Possible 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

    Create a service binding

    Definition
    
    POST /v3/service_bindings HTTP/1.1
    
    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": {
            "guid": "74f7c078-0934-470f-9883-4fddss5b8f13"
          },
          "service_instance": {
            "guid": "8bfe4c1b-9e18-45b1-83be-124163f31f9e"
          },
        },
        "data": {
          "parameters": {
            "some_object_id": "for_the_service_broker"
          }
        }
      }'
    
    Example Response
    
    HTTP/1.1 201 Created
    
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "type": "app",
      "data": {
        "credentials": {
          "super-secret": "password"
        },
        "syslog_drain_url": "syslog://drain.url.com",
        "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"
        }
      }
    }
    
    

    This endpoint creates a new service binding.

    Body Parameters

    Get a service binding

    Definition
    
    GET /v3/service_bindings/:guid HTTP/1.1
    
    Example Request
    
    curl "https://api.example.org/v3/service_bindings/[guid]" \
      -X GET \
      -H "Authorization: bearer [token]"
    
    Example Response
    
    HTTP/1.1 200 OK
    
    {
      "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
      "type": "app",
      "data": {
        "credentials": {
          "super-secret": "password"
        },
        "syslog_drain_url": "syslog://drain.url.com",
        "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"
        }
      }
    }
    
    

    This endpoint retrieves a specific service binding.

    Body Parameters

    No arguments

    Delete a service binding

    Definition
    
    DELETE /v3/service_bindings/:guid HTTP/1.1
    
    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
    

    This endpoint deletes a specific service binding.

    Body Parameters

    No arguments

    List service bindings

    Definition
    
    GET /v3/service_bindings HTTP/1.1
    
    Example Request
    
    curl "https://api.example.org/v3/service_bindings" \
      -X GET \
      -H "Authorization: bearer [token]"
    
    Example Response
    
    HTTP/1.1 200 OK
    
    {
      "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.com",
            "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.com",
            "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.

    Query Parameters

    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

    List spaces

    Definition
    
    GET /v3/spaces HTTP/1.1
    
    Example Request
    
    curl "https://api.example.org/v3/spaces" \
      -X GET \
      -H "Authorization: bearer [token]"
    
    Example Response
    
    HTTP/1.1 200 OK
    
    {
      "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",
          "links": {}
        },
        {
          "guid": "d4c91047-7b29-4fda-b7f9-04033e5c9c9f",
          "created_at": "2017-02-02T00:14:30Z",
          "updated_at": "2017-02-02T00:14:30Z",
          "name": "space2",
          "links": {}
        }
      ]
    }
    
    

    This endpoint retrieves the spaces the user has access to.

    Query Parameters

    Assign an isolation segment

    Definition
    
    PATCH /v3/spaces/:guid/relationships/isolation_segment HTTP/1.1
    
    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
    
    {
      "data": {
        "guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment"
        }
      }
    }
    
    

    This endpoint assigns an isolation segment to the space. The space’s parent organization must have already been entitled to the isolation_segment.

    Apps will not run in the newly assigned isolation segment until they are restarted.

    Body Parameters

    Get assigned isolation segment

    Definition
    
    GET /v3/spaces/:guid/relationships/isolation_segment HTTP/1.1
    
    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
    
    {
      "data": {
        "guid": "e4c91047-3b29-4fda-b7f9-04033e5a9c9f"
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment"
        }
      }
    }
    
    

    This endpoint retrieves the isolation segment currently assigned to the space.

    Body Parameters