Introduction

Overview

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

• GA - Running one-off tasks on Cloud Foundry
• Experimental - Applications consisting of several processes via a Procfile
• Experimental - Direct access to application packages and droplets

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

• The Cloud Foundry V2 API is still the primary API for interacting with Cloud Foundry.
• Running Tasks

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

• guid string

  The unique identifier for the resource

• created_at datetime

  The ISO8601 compatible date and time when resource was created.

• updated_at datetime

  The ISO8601 compatible date and time when resource was last updated.

• links link object

  Provide URLs to related resources and actions for the current resource.

Links

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.

The link object

• href string

  The absolute URL.

• method string

  An optional field containing the HTTP method to be used when following the URL.

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

• code integer

  A numeric code for this error

• title string

  Short description of the error.

• detail string

  Detailed description of the error.

Pagination

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

The pagination object

Example Paginated Response

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

      "name": "Bob",

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

• total_results integer

  Total number of resources for all pages

• total_pages integer

  Total number of pages

• first link object

  Link to the first page

• last link object

  Link to the last page

• next link object

  Link to the next page

• previous link object

  Link to the previous page

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

• guid string

  Unique GUID for the task

• sequence_id integer

  User-facing id of the task. This number is unique for every task associated with a given app.

• name string

  User-facing name of the task.

• command string

  Command that will be executed. This field may be excluded based on a user’s role.

• disk_in_mb integer

  Amount of disk to allocate for the task in MB.

• memory_in_mb integer

  Amount of memory to allocate for the task in MB.

• state string

  State of the task. Possible states are PENDING, RUNNING, SUCCEEDED, CANCELING, and FAILED

• droplet_guid string

  The guid of the droplet that will be used to run the command.

• result object

  Results from the task

• result[failure_reason] string

  Null if the task succeeds, contains the error message if it fails.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

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

• command required

  Command that will be executed

• name optional

  User-facing name of the task

• memory_in_mb optional

  Amount of memory to allocate for the task in MB. Defaults to operater-configurable ‘default_app_memory’ when not specified.

• disk_in_mb optional

  Amount of disk to allocate for the task in MB. Defaults to operater-configurable 'default_app_disk_in_mb’ when not specified.

• droplet_guid optional

  The guid of the droplet that will be used to run the command. Defaults to the app’s current droplet when not specified.

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

• app_guids optional string

  Comma-delimited list of app guids to filter by.
  Example: app_guids=app_guid1,app_guid2

• names optional array of strings

  Comma-delimited list of task names to filter by.
  Example: names=name1,name2

• guids optional string

  Comma-delimited list of task guids to filter by.

• organization_guids optional string

  Comma-delimited list of organization guids to filter by.
  Example: organization_guids=organization_guid1,organization_guid2

• space_guids optional string

  Comma-delimited list of space guids to filter by.
  Example: space_guids=space_guid1,space_guid2

• states optional string

  Comma-delimited list of task states to filter by.

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

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

• guids optional string

  Comma-delimited list of task guids to filter by.

• names optional string

  Comma-delimited list of task names to filter by.

• sequence_ids optional integer

  Comma delimited list of sequence ids to filter by. Possible values are integers >= 1

• states optional string

  Comma delimited list of task states to filter by.

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

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

• guid string

  Unique GUID for the app.

• name string

  An arbitrary name of the app.

• desired_state string

  Current desired state of the app. Can either be STOPPED or STARTED.

• total_desired_instances integer

  Number of desired instances of the application.

• lifecycle object

  Provides the lifecycle object for the application.

• environment_variables object

  Provides the list of custom environment variables available to the application.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

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

• name required

  Name of the App

• relationships[space][guid] required

  Guid for a particular space

• environment_variables optional

  Environment variables to be used for the App when running.

• lifecycle optional

  Lifecycle to be used when creating the app. Note: If no lifecycle is provided, lifecycle type defaults to buildpack. Data is a required field in lifecycle.

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

• name optional

  Name of the App.

• environment_variables optional

  Environment variables to be used for the App when running.

• lifecycle optional

  Lifecycle to be used when updating the app. Note: If no lifecycle is provided, lifecycle type defaults to buildpack. Data is a required field in lifecycle.

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

• guids optional string

  Comma-delimited list of app guids to filter by.
  Example: guids=guid1,guid2

• names optional array of strings

  Comma-delimited list of app names to filter by.
  Example: names=name1,name2

• organization_guids optional string

  Comma-delimited list of organization guids to filter by.
  Example: organization_guids=organization_guid1,organization_guid2

• space_guids optional string

  Comma-delimited list of space guids to filter by.
  Example: space_guids=space_guid1,space_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, name.

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

• guid string

  Unique GUID for the droplet.

• state string

  State of the droplet. Possible states are “STAGING”, “STAGED”, “COPYING”, “FAILED”, or “EXPIRED”.

• error string

  A string describing the last error during the droplet lifecycle.

• lifecycle object

  An object describing the lifecycle that was configured or discovered.

• staging_memory_in_mb integer

  The maximum memory in mb that can be used by a droplet.

• staging_disk_in_mb integer

  The disk quota applied during droplet staging.

• result object

  An object describing the result of a droplet that has completed staging (where state is “STAGED”, “FAILED”, or “EXPIRED”). Droplets in uncomplete states return null result.

• environment_variables object

  Environment variables to be used when staging the droplet. Variables in the CF_ and VCAP_ scopes will be populated by the system.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

The lifecycle object

Lifecycle objects describe buildpacks or docker images.

Lifecycle object for buildpack droplets

• type string

  “buildpack”

• data[‘buildpacks’] array of strings

  A list of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack. Currently only supports at most one buildpack.

• data['stack’] string

  The root filesystem to use with the buildpack, for example “cflinuxfs2”

Lifecycle object for docker

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

• type string

  “docker”

• data string

  An empty object should be passed: “{}”

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

• environment_variables optional

  Environment variables ot use during staging. Environment variable names may not start with VCAP_ or CF_. PORT is not a valid environment variable.

• staging_memory_in_mb optional

  Memory limit used to stage package

• staging_disk_in_mb optional

  Disk limit used to stage package

• lifecycle optional

  Lifecycle information for a droplet. If not provided, it will default to what is specified on the app. If the app does not have lifecycle information, it will default to a buildpack.

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

• guid optional

  Source guid of the droplet to be copied

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

• app_guids optional string

  Comma-delimited list of app guids to filter by.
  Example: app_guids=app_guid1,app_guid2

• guids optional string

  Comma-delimited list of droplet guids to filter by.
  Example: guids=guid1,guid2

• organization_guids optional string

  Comma-delimited list of organization guids to filter by.
  Example: organization_guids=organization_guid1,organization_guid2

• space_guids optional string

  Comma-delimited list of space guids to filter by.
  Example: space_guids=space_guid1,space_guid2

• states optional string

  Comma-delimited list of droplet states to filter by.

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

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

• guids optional string

  Comma-delimited list of droplet guids to filter by.
  Example: guids=guid1,guid2

• page optional

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

• states optional

  Comma-delimited list of droplet states to filter by.
  Example: states=STAGING

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

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

• guids optional string

  Comma-delimited list of droplet guids to filter by.
  Example: guids=guid1,guid2

• page optional

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

• states optional

  Comma-delimited list of droplet states to filter by.
  Example: states=STAGING

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

Isolation Segments

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

The isolation_segment object

• guid string

  Unique GUID for the isolation_segment.

• name string

  An arbitrary name of the isolation segment.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

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

• name required

  Name of the Isolation Segment. Isolation Segment names must be unique across the entire system, and case is ignored when checking for uniqueness.

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

• name

  Name of the Isolation Segment. The name must be unique across the entire system, and case is ignored when checking for uniqueness.

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

• guids optional string

  Comma-delimited list of isolation_segment guids to filter by.
  Example: guids=guid1,guid2

• names optional array of strings

  Comma-delimited list of isolation segment names to filter by.
  Example: names=name1,name2

• organization_guids optional string

  Comma-delimited list of organization guids to filter by.
  Example: organization_guids=organization_guid1,organization_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.

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

• data

  Array of organizations, each specified by its guid, to be entitled.

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

• guid string

  Unique GUID for the organization

• name string

  User-facing name of the organization.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

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

• names optional array of strings

  Comma-delimited list of organization names to filter by.
  Example: names=name1,name2

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

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

• names optional array of strings

  Comma-delimited list of organization names to filter by.
  Example: names=name1,name2

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

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

• data[guid]

  Guid of isolation segment to set as default. Setting data to null will remove the default isolation segment.

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

• guid string

  Unique GUID for the package.

• type string

  Package type. Possible values are “bits”, “docker”.

• data object

  Data for docker packages. Can be empty for bits packages.

• state string

  State of the package. Possible states are “PROCESSING_UPLOAD”, “READY”, “FAILED”, “AWAITING_UPLOAD”, “COPYING”, and “EXPIRED”.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

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

• relationships[‘app’]['guid’] required

  Guid of the app to which you would like to associate the package.

• type required

  Package type. Possible values are “bits”, “docker”.

• data optional

  Data for docker packages. Can be empty for bits packages.

• data['image’] optional

  Location of docker image. Required for docker packages.

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

• bits required

  A binary zip file containing the package bits

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

• source_package_guid required

  Source of package to copy from

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

• app_guids optional string

  Comma-delimited list of app guids to filter by.
  Example: app_guids=app_guid1,app_guid2

• guids optional string

  Comma-delimited list of package guids to filter by.
  Example: guids=guid1,guid2

• organization_guids optional string

  Comma-delimited list of organization guids to filter by.
  Example: organization_guids=organization_guid1,organization_guid2

• space_guids optional string

  Comma-delimited list of space guids to filter by.
  Example: space_guids=space_guid1,space_guid2

• states optional string

  Comma-delimited list of package states to filter by.

• types optional string

  Comma-delimited list of package types to filter by.

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

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

• guids optional string

  Comma-delimited list of package guids to filter by.
  Example: guids=guid1,guid2

• states optional string

  Comma-delimited list of package states to filter by.

• types optional string

  Comma-delimited list of package types to filter by.

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

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

• guid string

  Unique GUID for the process.

• type string

  Process type. A unique identifier for processes belonging to an app.

• command string

  The command is used to start the process.

• instances integer

  The number of instances to run.

• memory_in_mb integer

  The memory in mb allocated per instance.

• disk_in_mb integer

  The disk in mb allocated per instance.

• ports array of integers

  The ports that will be open to accept traffic in the container running the process. An empty array will bind no ports to the application. web type processes will default to using port 8080 when ports are not provided. All other process types will default to no ports.

• health_check health_check object

  The health check to perform on the process. See health_check for more information.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

The health_check object

• type string

  The type of health check to perform. Valid values are port and process

• data[‘timeout’] integer

  The time in seconds that the health check can fail before the process is restarted.

The process stats object

• type string

  Process type. A unique identifier for processes belonging to an app.

• index integer

  The zero-based index of running intances.

• state string

  The state of the instance. RUNNING, CRASHED, STARTING

• usage[‘time’] datetime

  The time when the usage was requested.

• usage['cpu’] number

  The current cpu usage of the instance.

• usage['mem’] integer

  The current memory usage of the instance.

• usage['disk’] integer

  The current disk usage of the instance.

• host string

  The host the instance is running on.

• instance_ports object

  JSON array of port mappings between the network-exposed port used to communicate with the app (“external”) and port opened to the running process that it can listen on (“internal”).

• uptime integer

  The uptime in seconds for the instance.

• mem_quota integer

  The maximum memory the instance is allowed to use.

• disk_quota integer

  The maximum disk the instance is allowed to use.

• fds_quota integer

  The maximum file descriptors the instance is allowed to use.

Get a process

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

• command optional

  The command that will be used to start the process.

• ports optional

  The ports that will be open to accept traffic in the container running the process. An empty array will bind no ports to the application. web type processes will default to using port 8080 when ports are not provided. All other process types will default to no ports.

• health_check optional

  The health check to perform on the process. See health_check for more information.

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

• instances optional

  The number of instances.

• memory_in_mb optional

  The memory in mb allocated per instance.

• disk_in_mb optional

  The disk in mb allocated per instance.

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

• app_guids optional string

  Comma-delimited list of app guids to filter by.
  Example: app_guids=app_guid1,app_guid2

• guids optional string

  Comma-delimited list of process guids to filter by.
  Example: guids=guid1,guid2

• organization_guids optional string

  Comma-delimited list of organization guids to filter by.
  Example: organization_guids=organization_guid1,organization_guid2

• space_guids optional string

  Comma-delimited list of space guids to filter by.
  Example: space_guids=space_guid1,space_guid2

• types optional string

  Comma-delimited list of process types to filter by.

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

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

• app_guids optional string

  Comma-delimited list of app guids to filter by.
  Example: app_guids=app_guid1,app_guid2

• guids optional string

  Comma-delimited list of process guids to filter by.
  Example: guids=guid1,guid2

• organization_guids optional string

  Comma-delimited list of organization guids to filter by.
  Example: organization_guids=organization_guid1,organization_guid2

• space_guids optional string

  Comma-delimited list of space guids to filter by.
  Example: space_guids=space_guid1,space_guid2

• types optional string

  Comma-delimited list of process types to filter by.

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

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

• guid string

  Unique GUID for the route mapping.

• app_port integer

  The port that traffic will be routed to for the mapped process.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

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

• app_port optional

  The port that traffic will be routed to for the mapped process. Defaults to 8080

• relationships[‘app’]['guid’] required

  Guid of the app to which you would like to map the route.

• relationships['route’]['guid’] required

  Guid of the route to which you would like to map the app.

• relationships['process’]['type’] optional

  Type of the process on the app to which you would like to map the route. Defaults to web

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

• app_guids optional string

  Comma-delimited list of app guids to filter by.
  Example: app_guids=app_guid1,app_guid2

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

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

• guid string

  Unique GUID for the service binding

• type string

  Service binding type. Currently only possible value is “app”.

• data object

  Data returned from the service broker for the service instance. Currently possible values are “credentials”, “syslog_drain_url” and (experimental) “volume_mounts”.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

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

• type required

  Service binding type. Currently, the only possible value is “app”.

• relationships[‘app’]['guid’] required

  Guid of the app to which you would like to bind the service instance.

• relationships['service_instance’]['guid’] required

  Guid of the service instance to which you would like to bind the app.

• data['parameters’] optional

  Additional configuration parameters for the service binding.

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

• app_guids optional string

  Comma-delimited list of app guids to filter by.
  Example: app_guids=app_guid1,app_guid2

• service_instance_guids optional string

  Comma-delimited list of service_instance_guids types to filter by. Example: service_instance_guids=guid1,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.

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

• guid string

  Unique GUID for the space

• name string

  User-facing name of the space.

• created_at datetime

  The time with zone when the object was created.

• updated_at datetime

  The time with zone when the object was last updated.

• links object

  Links to related resources.

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

• names optional array of strings

  Comma-delimited list of space names to filter by.
  Example: names=name1,name2

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

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

• data[guid]

  Guid of the isolation segment to assign to the space. Setting data to null will unassign the isolation segment.

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

• data[guid]

  Guid of the isolation segment to assign to the space. data will be null if there is no isolation segment assigned.