NAV
curl

Introduction

Overview

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

More Resources

Concepts

Authentication

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

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

Authorization

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

OAuth2 Scopes

Scope Description
cloud_controller.admin This scope provides read and write access to all resources
cloud_controller.admin_read_only This scope provides read only access to all resources
cloud_controller.read This scope provides read access to resources based on user roles
cloud_controller.write This scope provides write access to resources based on user roles

Cloud Foundry User Roles

Role Description
SpaceManager This role provides Space management access
SpaceDeveloper This role allows developers to create and manage apps and services in a Space
SpaceAuditor This role allows read-only access to a Space for auditing purposes

Status Codes

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

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

Resources

A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object.

A resource consists of several required resource fields and other attributes specific to the resource.

Required fields

Example Person Resource

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

  "name": "Bob",

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

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

Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET.

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": "The request is semantically invalid: something went wrong"
    }
  ]
}

Pagination

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

The pagination object

Example Paginated Response

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

      "name": "Bob",

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

Workflows

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

Push V2 App and Run a V3 Task

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

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

For more information, see Create a task.

Resources

Tasks

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

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

The task object

Create a task

Definition

POST /v3/apps/:guid/tasks HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/tasks" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -d '{ "command": "rake db:migrate" }'

Example Response

HTTP/1.1 202 Accepted

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

This endpoint creates a new task.

Body Parameters

Get a task

Definition

GET /v3/tasks/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/tasks/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

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

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

Body Parameters

No arguments

Cancel a task

Definition

PUT /v3/tasks/:task_guid/cancel HTTP/1.1

Example Request

curl "https://api.example.org/v3/tasks/[guid]/cancel" \
  -X PUT \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted

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

This endpoint cancels a running task.

Canceled tasks will initially be in state “CANCELING” and will move to state “FAILED” once the cancel request has been processed.

Cancel requests are idempotent and will be processed according to the state of the task when the request is executed.

Canceling a task that is in “SUCCEEDED” or “FAILED” state will return an error.

Body Parameters

No arguments

List tasks

Definition

GET /v3/tasks HTTP/1.1

Example Request

curl "https://api.example.org/v3/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

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

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

Query Parameters

List tasks for an app

Definition

GET /v3/apps/:guid/tasks HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/:guid/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

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

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

Query Parameters

Experimental Resources

Apps

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

The app object

Create an app

Definition

POST /v3/apps HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -d '{
    "name": "my_app",
    "environment_variables": {
      "HTTP_PROXY": "http://proxy.example.com"
    },
    "lifecycle": {
      "type": "buildpack",
      "data": {
        "buildpack": "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": {
      "buildpack": "java_buildpack",
      "stack": "cflinuxfs2"
    }
  },
  "environment_variables": {
    "HTTP_PROXY": "http://proxy.example.com"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "route_mappings": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/start",
      "method": "PUT"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
      "method": "PUT"
    }
  }
}

This endpoint creates a new app.

Body Parameters

Get an app

Definition

GET /v3/apps/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "guid": "1cb006ee-fb05-47e1-b541-c34179ddc446",
  "name": "my_app",
  "desired_state": "STOPPED",
  "total_desired_instances": 0,
  "created_at": "2016-03-17T21:41:30Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpack": "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]" \
  -d '{
    "name": "my_app",
    "environment_variables": {
      "HTTP_PROXY": "http://proxy.example.com"
    },
    "lifecycle": {
      "type": "buildpack",
      "data": {
        "buildpack": "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": {
      "buildpack": "java_buildpack",
      "stack": "cflinuxfs2"
    }
  },
  "environment_variables": {
    "HTTP_PROXY": "http://proxy.example.com"
  },
  "links": {
    "self": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "route_mappings": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "packages": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "droplet": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/start",
      "method": "PUT"
    },
    "stop": {
      "href": "https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/stop",
      "method": "PUT"
    }
  }
}

This endpoint updates an app.

Body Parameters

Set current droplet for an app

Definition

PUT /v3/apps/:guid/droplets/current HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/droplets/current" \
  -X PUT \
  -H "Authorization: bearer [token]" \
  -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": {
      "buildpack": null,
      "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": "sha1",
      "value": "0cd90dd63dd9f42db25340445d203fba25c69cf6"
    },
    "buildpack": {
      "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": {
      "buildpack": null,
      "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": "sha1",
      "value": "0cd90dd63dd9f42db25340445d203fba25c69cf6"
    },
    "buildpack": {
      "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": {
      "buildpack": "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": {
      "buildpack": "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": {
          "buildpack": "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": {
          "buildpack": "ruby_buildpack",
          "stack": "cflinuxfs2"
        }
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "links": {
        "self": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
        },
        "space": {
          "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "processes": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes"
        },
        "route_mappings": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/route_mappings"
        },
        "packages": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages"
        },
        "droplet": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current"
        },
        "droplets": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets"
        },
        "tasks": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks"
        },
        "start": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/start",
          "method": "PUT"
        },
        "stop": {
          "href": "https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/stop",
          "method": "PUT"
        }
      }
    }
  ]
}

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

Query Parameters

Droplets

Droplets are created by staging an application package. There are two types (lifecycles) of droplets: buildpack and docker. In the case of the buildpacks, the droplet contains the bits produced by the buildpack, typically application code and dependencies.

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

The droplet object

The lifecycle object

Lifecycle objects describe buildpacks or docker images.

Lifecycle object for buildpack droplets

Lifecycle object for docker

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

Create a droplet

Definition

POST /v3/packages/:guid/droplets HTTP/1.1

Example Request

curl "https://api.example.org/v3/packages/[guid]/droplets" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -d '{
    "environment_variables": {
      "CUSTOM_ENV_VAR": "hello"
    },
    "lifecycle": {
      "type": "buildpack",
      "data": {
        "buildpack": "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": {
      "buildpack": null,
      "stack": null
    }
  },
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 4096,
  "result": null,
  "environment_variables": {
    "CF_STACK": "cflinuxfs2",
    "VCAP_APPLICATION": {
      "limits": {
        "mem": 1024,
        "disk": 4096,
        "fds": 16384
      },
      "application_id": "7b34f1cf-7e73-428a-bb5a-8a17a8058396",
      "application_version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "application_name": "my_app",
      "application_uris": [
        "my_app.example.com"
      ],
      "version": "d5985d64-c455-44d0-99a5-285b6521f84c",
      "name": "my_app",
      "space_name": "my_space",
      "space_id": "2f35885d-0c9d-4423-83ad-fd05066f8576",
      "uris": [
        "my_app.example.com"
      ],
      "users": null
    },
    "MEMORY_LIMIT": "1024m",
    "VCAP_SERVICES": {}
  },
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
      "method": "PUT"
    }
  }
}

This endpoint creates a new droplet from a package.

Body Parameters

Copy a droplet

Definition

POST /v3/droplets/:guid/copy HTTP/1.1

Example Request

curl "https://api.example.org/v3/droplets/[guid]/copy" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -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": {
      "buildpack": null,
      "stack": null
    }
  },
  "staging_memory_in_mb": 1024,
  "staging_disk_in_mb": 4096,
  "result": null,
  "environment_variables": {},
  "created_at": "2016-03-28T23:39:34Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
      "method": "PUT"
    }
  }
}

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

Query Parameters

Get a droplet

Definition

GET /v3/droplets/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/droplets/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
  "state": "STAGED",
  "error": null,
  "lifecycle": {
    "type": "buildpack",
    "data": {
      "buildpack": null,
      "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": "sha1",
      "value": "0cd90dd63dd9f42db25340445d203fba25c69cf6"
    },
    "buildpack": {
      "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": {
          "buildpack": null,
          "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": "sha1",
          "value": "0cd90dd63dd9f42db25340445d203fba25c69cf6"
        },
        "buildpack": {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14"
        },
        "stack": "cflinuxfs2"
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": null,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "created_at": "2016-03-17T00:00:01Z",
      "updated_at": "2016-03-17T21:41:32Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

This endpoint retrieves the droplets the user has access to.

Query Parameters

List droplets for an app

Definition

GET /v3/apps/:guid/droplets HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpack": null,
          "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": "sha1",
          "value": "0cd90dd63dd9f42db25340445d203fba25c69cf6"
        },
        "buildpack": {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14"
        },
        "stack": "cflinuxfs2"
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": null,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "created_at": "2016-03-17T00:00:01Z",
      "updated_at": "2016-03-17T21:41:32Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

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

Body Parameters

List droplets for a package

Definition

GET /v3/packages/:guid/droplets HTTP/1.1

Example Request

curl "https://api.example.org/v3/packages/[guid]/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "585bc3c1-3743-497d-88b0-403ad6b56d16",
      "state": "STAGED",
      "error": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpack": null,
          "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": "sha1",
          "value": "0cd90dd63dd9f42db25340445d203fba25c69cf6"
        },
        "buildpack": {
          "name": "ruby_buildpack",
          "detect_output": "ruby 1.6.14"
        },
        "stack": "cflinuxfs2"
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "created_at": "2016-03-28T23:39:34Z",
      "updated_at": "2016-03-28T23:39:47Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    },
    {
      "guid": "fdf3851c-def8-4de1-87f1-6d4543189e22",
      "state": "STAGING",
      "error": null,
      "lifecycle": {
        "type": "docker",
        "data": {}
      },
      "staging_memory_in_mb": 1024,
      "staging_disk_in_mb": 4096,
      "result": null,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "created_at": "2016-03-17T00:00:01Z",
      "updated_at": "2016-03-17T21:41:32Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "https://api.example.org/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

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

Body Parameters

Isolation Segments

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

The isolation_segment object

Create an isolation segment

Definition

POST /v3/isolation_segments HTTP/1.1

Example Request

curl "https://api.example.org/v3/isolation_segments" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -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"
      },
      "spaces": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
      }
   }
}

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

Body Parameters

Get an isolation segment

Definition

GET /v3/isolation_segments/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/isolation_egments/[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"
      },
      "spaces": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
      }
   }
}

This endpoint retrieves an isolation segment.

Update an isolation segment

Definition

PUT /v3/isolation_segments/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X PUT \
  -H "Authorization: bearer [token]" \
  -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"
      },
      "spaces": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
      }
   }
}

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

Body Parameters

Delete an isolation segment

Definition

DELETE /v3/isolation_segments/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

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

List isolation segments

Definition

GET /v3/isolation_segments HTTP/1.1

Example Request

curl "https://api.example.org/v3/isolation_segments" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
   "pagination": {
      "total_results": 11,
      "total_pages": 3,
      "first": {
         "href": "https://api.example.org/v3/isolation_segments?page=1&per_page=5"
      },
      "last": {
         "href": "https://api.example.org/v3/isolation_segments?page=3&per_page=5"
      },
      "next": {
         "href": "https://api.example.org/v3/isolation_segments?page=2&per_page=5"
      },
      "previous": null
   },
   "resources": [
      {
         "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
         "name": "an_isolation_segment",
         "created_at": "2016-10-19T20:25:04Z",
         "updated_at": "2016-11-08T16:41:26Z",
         "links": {
            "self": {
               "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
            },
            "spaces": {
               "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/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"
            },
            "spaces": {
               "href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac/relationships/spaces"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/68d54d31-9b3a-463b-ba94-e8e4c32edbac/relationships/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"
            },
            "spaces": {
               "href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03/relationships/spaces"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/ecdc67c3-a71e-43ff-bddf-048930b8cd03/relationships/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"
            },
            "spaces": {
               "href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0/relationships/spaces"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/424c89e4-4353-46b7-9bf4-f90bd9bacac0/relationships/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": {
            "spaces": {
               "href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7/relationships/spaces"
            },
            "organizations": {
               "href": "https://api.example.org/v3/isolation_segments/0a79fcec-a648-4eb8-a6c3-2b5be39047c7/relationships/organizations"
            }
         }
      }
   ]
}

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

Query Parameters

Entitle one or more organizations for an isolation segment

Definition

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

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -d '{
    "data": [
      { "guid":"org-guid-1" },
      { "guid":"org-guid-2" }
    ]
  }' 

Example Response

HTTP/1.1 201 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"
      },
      "spaces": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces"
      },
      "organizations": {
         "href": "https://api.example.org/v3/isolation_segments/b19f6525-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations"
      }
   }
}

This endpoint entitles the specified organizations for the isolation segment. Only Admins can entitle organizations for isolation segments. If an organization is not already entitled for any other isolation segment, then this isolation segment automatically becomes the default for that organization.

Body Parameters

Revoke entitlement to isolation segment for one or more organizations

Definition

DELETE /v3/isolation_segments/:guid/relationships/organizations HTTP/1.1

Example Request

curl "https://api.example.org/v3/isolation_segments/[guid]/relationships/organizations" \
  -X DELETE \
  -H "Authorization: bearer [token]" \
  -d '{
    "data": [
      { "guid":"org-guid-1" },
      { "guid":"org-guid-2" }
    ]
  }' 

Example Response

HTTP/1.1 204 No Content

This endpoint revokes the entitlements for the specified organizations 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, and the organization has more than one isolation segment, the entitlement cannot be revoked.

Body Parameters

List organizations for an isolation segment

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": [
    {
      "name": "org1",
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac",
      "link": "/v2/organizations/68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "name": "org2",
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
      "link": "/v2/organizations/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ]
}

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 for an isolation segment

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": [
    {
      "name": "space1",
      "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac",
      "link": "/v2/spaces/68d54d31-9b3a-463b-ba94-e8e4c32edbac"
    },
    {
      "name": "space2",
      "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c",
      "link": "/v2/spaces/b19f6525-cbd3-4155-b156-dc0c2a431b4c"
    }
  ]
}

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.

Packages

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

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

The package object

Create a package

Definition

POST /v3/apps/:guid/packages HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/packages" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -d '{
    "type": "docker",
    "data": {
      "image": "registry/image:latest"
    }
  }'

Example Response

HTTP/1.1 201 Created

{
  "guid": "4cb65058-f04f-458f-aca1-5f4e43de6407",
  "type": "docker",
  "data": {
    "hash": {
      "type": "sha1",
      "value": null
    },
    "error": null,
    "image": "registry/image:latest"
  },
  "state": "READY",
  "created_at": "2015-11-03T00:53:54Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links":
  {
    "self": {
      "href": "https://api.example.org/v3/packages/4cb65058-f04f-458f-aca1-5f4e43de6407"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/d8b8148d-5798-44de-821a-64b85b15e968"
    }
  }
}

This endpoint creates a new package.

Body Parameters

Get a package

Definition

GET /v3/packages/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/packages/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

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

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

Form Parameters

Download package bits

Definition

GET /v3/packages/:guid/download HTTP/1.1

Example Request

curl "https://api.example.org/v3/packages/[guid]/download" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 302 Found

You are being redirected.

This endpoint downloads the bits of an existing package.

When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits. If the client is automatically following redirects, then the OAuth token that was used to communicate with Cloud Controller will be replayed on the new redirect request. Some blobstores may reject the request in that case. Clients may need to follow the redirect without including the OAuth token.

Body Parameters

No arguments

Copy a Package

Definition

POST /v3/apps/:guid/packages HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/packages?source_package_guid=[guid]" \
  -X POST \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 201 Created

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

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

Query Parameters

Delete a package

Definition

DELETE /v3/packages/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/packages/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

This endpoint deletes a specific package.

Body Parameters

No arguments

List packages

Definition

GET /v3/packages HTTP/1.1

Example Request

curl "https://api.example.org/v3/packages" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/packages?types=bits%2Cdocker&page=2&per_page=2"
    },
    "next": {
      "href": null
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "a57fd932-85db-483a-a27e-b00efbb3b0a4",
      "type": "bits",
      "data": {
        "hash": {
          "type": "sha1",
          "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": "sha1",
          "value": null
        },
        "error": null,
        "image": "repository/docker-image:latest"
      },
      "state": "READY",
      "created_at": "2015-11-03T00:53:54Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/packages/8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
        }
      }
    }
  ]
}

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

Query Parameters

List packages for an app

Definition

GET /v3/apps/:guid/packages HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/packages" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 1,
    "total_pages": 1,
    "first": {
      "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
    },
    "next": null,
    "previous": null
  },
  "resources": [
    {
      "guid": "752edab0-2147-4f58-9c25-cd72ad8c3561",
      "type": "bits",
      "data": {
        "error": null,
        "hash": {
          "type": "sha1",
          "value": null
        }
      },
      "state": "READY",
      "created_at": "2016-03-17T21:41:09Z",
      "updated_at": "2016-06-08T16:41:26Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561"
        },
        "upload": {
          "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/upload",
          "method": "POST"
        },
        "download": {
          "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/download",
          "method": "GET"
        },
        "stage": {
          "href": "https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/droplets",
          "method": "POST"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69"
        }
      }
    }
  ]
}

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

Query Parameters

Processes By Guid

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

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

The process object

The health_check object

The process stats object

Get a process

Definition

GET /v3/processes/:guid HTTP/1.1

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

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]" \
  -d '{ "command": "rackup" }'

Example Response

HTTP/1.1 200 OK

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "ports": [8080],
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
      "method": "PUT"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

This endpoint updates an existing process.

Body Parameters

Scale a process

Definition

PUT /v3/processes/:guid/scale HTTP/1.1

Example Request

curl "https://api.example.org/v3/processes/[guid]/scale" \
  -X PUT \
  -H "Authorization: bearer [token]" \
  -d '{
    "instances": 5,
    "memory_in_mb": 256,
    "disk_in_mb": 1024,
  }'

Example Response

HTTP/1.1 202 OK

{
  "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
  "type": "web",
  "command": "rackup",
  "instances": 5,
  "memory_in_mb": 256,
  "disk_in_mb": 1024,
  "ports": [8080],
  "health_check": {
    "type": "port",
    "data": {
      "timeout": null
    }
  },
  "created_at": "2016-03-23T18:48:22Z",
  "updated_at": "2016-03-23T18:48:42Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
      "method": "PUT"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

This endpoint scales an existing process.

Body Parameters

Terminate a process instance

Definition

DELETE /v3/processes/:guid/instances/:index HTTP/1.1

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

Processes By App and Type

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

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

The process object

The health_check object

The process stats object

Get a process for an app

Definition

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

Example Request

curl "https://api.example.org/v3/apps/[guid]/processes/[type]" \
  -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 belonging to an app.

Body Parameters

No arguments

Get stats for a process for an app

Definition

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

Example Request

curl "https://api.example.org/v3/apps/[guid]/processes/[type]/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 belonging to an app.

Body Parameters

No arguments

Scale a process for an app

Definition

PUT /v3/apps/:guid/processes/:type/scale HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/processes/[type]/scale" \
  -X PUT \
  -H "Authorization: bearer [token]" \
  -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 belonging to an app.

Body Parameters

Terminate a process instance for an app

Definition

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

Example Request

curl "https://api.example.org/v3/apps/[guid]/processes/[type]/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 belonging to an app. 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 for an app

Definition

GET /v3/apps/:guid/processes HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/processes \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=1&per_page=2"
    },
    "last": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
    },
    "next": {
      "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "6a901b7c-9417-4dc1-8189-d3234aa0ab82",
      "type": "web",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 5,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "ports": [8080],
      "health_check": {
        "type": "port",
        "data": {
          "timeout": null
        }
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
        },
        "scale": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
          "method": "PUT"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
        }
      }
    },
    {
      "guid": "3fccacd9-4b02-4b96-8d02-8e865865e9eb",
      "type": "worker",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "instances": 1,
      "memory_in_mb": 256,
      "disk_in_mb": 1024,
      "ports": [],
      "health_check": {
        "type": "process",
        "data": {
          "timeout": null
        }
      },
      "created_at": "2016-03-23T18:48:22Z",
      "updated_at": "2016-03-23T18:48:42Z",
      "links": {
        "self": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
        },
        "scale": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/scale",
          "method": "PUT"
        },
        "app": {
          "href": "https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "https://api.example.org/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

This endpoint retrieves the processes belonging to an app.

Query Parameters

Route Mappings

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

The route_mapping object

Create a route mapping

Definition

POST /v3/route_mappings HTTP/1.1

Example Request

curl "https://api.example.org/v3/route_mappings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -d '{
    "relationships": {
      "app": {
        "guid": "[app-guid]"
      },
      "route": {
        "guid": "[route_guid]"
      }
    }
  }'

Example Response

HTTP/1.1 201 Created

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

This endpoint creates a new route mapping.

Body Parameters

Get a route mapping

Definition

GET /v3/route_mappings/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/route_mappings/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

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

This endpoint retrieves a specific route mapping.

Body Parameters

No arguments

Delete a route mapping

Definition

DELETE /v3/route_mappings/:guid HTTP/1.1

Example Request

curl "https://api.example.org/v3/route_mappings/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 204 No Content

This endpoint deletes a specific route mapping.

Body Parameters

No arguments

List route mappings

Definition

GET /v3/route_mappings HTTP/1.1

Example Request

curl "https://api.example.org/v3/route_mappings" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

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

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

Query Parameters

List route mappings for an app

Definition

GET /v3/apps/:guid/route_mappings HTTP/1.1

Example Request

curl "https://api.example.org/v3/apps/[guid]/route_mappings" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

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

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

Query Parameters

  • route_guids

    optional string

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

  • page

    optional

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

  • per_page

    optional

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

  • order_by

    optional

    Value to sort by. Defaults to ascending, or prepend with “-” to sort descending.
    Possible values are created_at or updated_at.

    • Service Bindings

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

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

    The service_binding object

    Create a service binding

    Definition

    POST /v3/service_bindings HTTP/1.1

    Example Request

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

    Example Response

    HTTP/1.1 201 Created

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.com",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

    This endpoint creates a new service binding.

    Body Parameters

    Get a service binding

    Definition

    GET /v3/service_bindings/:guid HTTP/1.1

    Example Request

    curl "https://api.example.org/v3/service_bindings/[guid]" \
  -X GET \
  -H "Authorization: bearer [token]"

    Example Response

    HTTP/1.1 200 OK

{
  "guid": "dde5ad2a-d8f4-44dc-a56f-0452d744f1c3",
  "type": "app",
  "data": {
    "credentials": {
      "super-secret": "password"
    },
    "syslog_drain_url": "syslog://drain.url.com",
    "volume_mounts": []
  },
  "created_at": "2015-11-13T17:02:56Z",
  "updated_at": "2016-06-08T16:41:26Z",
  "links": {
    "self": {
      "href": "https://api.example.org/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

    This endpoint retrieves a specific service binding.

    Body Parameters

    No arguments

    Delete a service binding

    Definition

    DELETE /v3/service_bindings/:guid HTTP/1.1

    Example Request

    curl "https://api.example.org/v3/service_bindings/[guid]" \
  -X DELETE \
  -H "Authorization: bearer [token]"

    Example Response

    HTTP/1.1 204 No Content

    This endpoint deletes a specific service binding.

    Body Parameters

    No arguments

    List service bindings

    Definition

    GET /v3/service_bindings HTTP/1.1

    Example Request

    curl "https://api.example.org/v3/service_bindings" \
  -X GET \
  -H "Authorization: bearer [token]"

    Example Response

    HTTP/1.1 200 OK

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

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

    Query Parameters

    curl