Overview

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

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

More Resources

The API team is currently focused on getting to MVP for V3. As such, this documentation doesn’t have all the information needed to interact with the V3 API. Here are a few resources that will help until we have everything documented here:

• Cloud Foundry Version 2 Documentation
• Tasks Proposal
• Upcoming talk at Cloud Foundry Summit
• CF CLI V3 Plugin - Experimental
• Push an app with cf curl
• CAPI Slack Channel

Apps

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

The app object

• guid string

  Unique GUID for the app.

• name string

  An arbitrary name of the app.

• desired_state string

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

• total_desired_instances integer

  Number of desired instances of the application.

• lifecycle object

  Provides the lifecycle object for the application.

• environment_variables object

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

• created_at datetime

  The time with zone when the app was created.

• updated_at datetime

  The time with zone with the package was last updated.

• links object

  Links to related resources.

Create an app

Definition

POST /v3/apps HTTP/1.1

Example Request

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

This endpoint creates a new app.

Body Parameters

• name required

  Name of the App

• relationships[space][guid] required

  Guid for a particular space

• environment_variables optional

  Environment variables to be used for the App when running.

• lifecycle optional

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

Get an app

Definition

GET /v3/apps/:guid HTTP/1.1

Example Request

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

This endpoint updates an app.

Body Parameters

• name optional

  Name of the App.

• environment_variables optional

  Environment variables to be used for the App when running.

• lifecycle optional

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

Set current droplet for an app

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": "/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "/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.[your-domain.com]/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": "/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "/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.[your-domain.com]/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": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "route_mappings": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "packages": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "droplet": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/start",
      "method": "PUT"
    },
    "stop": {
      "href": "/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.[your-domain.com]/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": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
    },
    "space": {
      "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "processes": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
    },
    "route_mappings": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
    },
    "packages": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
    },
    "droplet": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
    },
    "droplets": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
    },
    "tasks": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
    },
    "start": {
      "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/start",
      "method": "PUT"
    },
    "stop": {
      "href": "/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.[your-domain.com]/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.[your-domain.com]/v3/apps" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "/v3/apps?page=1&per_page=2"
    },
    "last": {
      "href": "/v3/apps?page=2&per_page=2"
    },
    "next": {
      "href": "/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": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446"
        },
        "space": {
          "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "processes": {
          "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/processes"
        },
        "route_mappings": {
          "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/route_mappings"
        },
        "packages": {
          "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/packages"
        },
        "droplet": {
          "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets/current"
        },
        "droplets": {
          "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/droplets"
        },
        "tasks": {
          "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/tasks"
        },
        "start": {
          "href": "/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/start",
          "method": "PUT"
        },
        "stop": {
          "href": "/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": null,
      "lifecycle": {
        "type": "buildpack",
        "data": {
          "buildpack": "ruby_buildpack",
          "stack": "cflinuxfs2"
        }
      },
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "links": {
        "self": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8"
        },
        "space": {
          "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "processes": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes"
        },
        "route_mappings": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/route_mappings"
        },
        "packages": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages"
        },
        "droplet": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current"
        },
        "droplets": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets"
        },
        "tasks": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks"
        },
        "start": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/start",
          "method": "PUT"
        },
        "stop": {
          "href": "/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/stop",
          "method": "PUT"
        }
      }
    }
  ]
}

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

Query Parameters

• guids optional string

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

• names optional array of strings

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

• organization_guids optional string

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

• space_guids optional string

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

• page optional

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

• per_page optional

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

• order_by optional

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

Droplets

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

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

The droplet object

• guid string

  Unique GUID for the droplet.

• state string

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

• error string

  A string describing the last error during the droplet lifecycle.

• lifecycle object

  An object describing the lifecycle that was configured or discovered.

• staging_memory_in_mb integer

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

• staging_disk_in_mb integer

  The disk quota applied during droplet staging.

• result object

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

• environment_variables object

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

• created_at datetime

  The time with zone when the app was created.

• updated_at datetime

  The time with zone with the package was last updated.

• links object

  Links to related resources.

The lifecycle object

Lifecycle objects describe buildpacks or docker images.

Lifecycle object for buildpack droplets

• type string

  “buildpack”

• data[‘buildpack’] string

  The name of the buildpack or a URL from which it may be downloaded, or null to auto-detect the buildpack

• data['stack’] string

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

Lifecycle object for docker

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

• type string

  “docker”

• data string

  An empty object should be passed: “{}”

Create a droplet

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
      "method": "PUT"
    }
  }
}

This endpoint creates a new droplet from a package.

Body Parameters

• environment_variables optional

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

• staging_memory_in_mb optional

  Memory limit used to stage package

• staging_disk_in_mb optional

  Disk limit used to stage package

• lifecycle optional

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

Copy a droplet

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
      "method": "PUT"
    }
  }
}

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

Query Parameters

• guid optional

  Source guid of the droplet to be copied

Get a droplet

Definition

GET /v3/droplets/:guid HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/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": "/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
    },
    "package": {
      "href": "/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
    },
    "app": {
      "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
    },
    "assign_current_droplet": {
      "href": "/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.[your-domain.com]/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.[your-domain.com]/v3/droplets" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "/v3/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "/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": "/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "/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": "/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

This endpoint retrieves the droplets the user has access to.

Query Parameters

• app_guids optional string

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

• guids optional string

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

• organization_guids optional string

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

• space_guids optional string

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

• states optional string

  Comma-delimited list of droplet states to filter by.

• page optional

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

• per_page optional

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

• order_by optional

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

List droplets for an app

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": "/v3/app/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "/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": "/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "/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": "/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

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

Body Parameters

• guids optional string

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

• page optional

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

• states optional

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

• per_page optional

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

• order_by optional

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

List droplets for a package

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": "/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50"
    },
    "last": {
      "href": "/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": "/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16"
        },
        "package": {
          "href": "/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92"
        },
        "app": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "/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": "/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22"
        },
        "package": {
          "href": "/v3/packages/c5725684-a02f-4e59-bc67-8f36ae944688"
        },
        "app": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396"
        },
        "assign_current_droplet": {
          "href": "/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets/current",
          "method": "PUT"
        }
      }
    }
  ]
}

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

Body Parameters

• guids optional string

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

• page optional

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

• states optional

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

• per_page optional

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

• order_by optional

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

Packages

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

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

The package object

• guid string

  Unique GUID for the package.

• type string

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

• data object

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

• state string

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

• created_at datetime

  The time with zone when the app was created.

• updated_at datetime

  The time with zone with the package was last updated.

• links object

  Links to related resources.

Create a package

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": null,
  "links":
  {
    "self": {
      "href": "/v3/packages/4cb65058-f04f-458f-aca1-5f4e43de6407"
    },
    "app": {
      "href": "/v3/apps/d8b8148d-5798-44de-821a-64b85b15e968"
    }
  }
}

This endpoint creates a new package.

Body Parameters

• type required

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

• data optional

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

• data[‘image’] optional

  Location of docker image. Required for docker packages.

Get a package

Definition

GET /v3/packages/:guid HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "stage": {
      "href": "/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/droplets",
      "method": "POST"
    },
    "app": {
      "href": "/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.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13"
    },
    "upload": {
      "href": "/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload",
      "method": "POST"
    },
    "download": {
      "href": "/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download",
      "method": "GET"
    },
    "stage": {
      "href": "/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/droplets",
      "method": "POST"
    },
    "app": {
      "href": "/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a"
    }
  }
}

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

Form Parameters

• bits required

  A binary zip file containing the package bits

Download package bits

Definition

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

Example Request

curl "https://api.[your-domain.com]/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.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3"
    },
    "stage": {
      "href": "/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3/droplets",
      "method": "POST"
    },
    "app": {
      "href": "/v3/apps/36208a68-562d-4f51-94ea-28bd8553a271"
    }
  }
}

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

Query Parameters

• source_package_guid required

  Source of package to copy from

Delete a package

Definition

DELETE /v3/packages/:guid HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/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.[your-domain.com]/v3/packages" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 2,
    "total_pages": 1,
    "first": {
      "href": "/v3/packages?types=bits%2Cdocker&page=1&per_page=2"
    },
    "last": {
      "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4"
        },
        "upload": {
          "href": "/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/upload",
          "method": "POST"
        },
        "download": {
          "href": "/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/download",
          "method": "GET"
        },
        "stage": {
          "href": "/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4/droplets",
          "method": "POST"
        },
        "app": {
          "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/packages/8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691"
        },
        "app": {
          "href": "/v3/apps/fa3558ce-1c4d-46fc-9776-54b9c8021745"
        }
      }
    }
  ]
}

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

Query Parameters

• app_guids optional string

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

• guids optional string

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

• organization_guids optional string

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

• space_guids optional string

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

• states optional string

  Comma-delimited list of package states to filter by.

• types optional string

  Comma-delimited list of package types to filter by.

• page optional

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

• per_page optional

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

• order_by optional

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

List packages for an app

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": "/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69/packages?states=READY&page=1&per_page=50"
    },
    "last": {
      "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561"
        },
        "upload": {
          "href": "/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/upload",
          "method": "POST"
        },
        "download": {
          "href": "/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/download",
          "method": "GET"
        },
        "stage": {
          "href": "/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561/droplets",
          "method": "POST"
        },
        "app": {
          "href": "/v3/apps/f2efe391-2b5b-4836-8518-ad93fa9ebf69"
        }
      }
    }
  ]
}

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

Query Parameters

• guids optional string

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

• states optional string

  Comma-delimited list of package states to filter by.

• types optional string

  Comma-delimited list of package types to filter by.

• page optional

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

• per_page optional

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

• order_by optional

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

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

• guid string

  Unique GUID for the process.

• type string

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

• command string

  The command is used to start the process.

• instances integer

  The number of instances to run.

• memory_in_mb integer

  The memory in mb allocated per instance.

• disk_in_mb integer

  The disk in mb allocated per instance.

• ports array of integers

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

• health_check health_check object

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

• created_at datetime

  The time with zone when the app was created.

• updated_at datetime

  The time with zone with the package was last updated.

• links object

  Links to related resources.

The health_check object

• type string

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

• data[‘timeout’] integer

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

The process stats object

• type string

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

• index integer

  The zero-based index of running intances.

• state string

  The state of the instance. RUNNING, CRASHED, STARTING

• usage[‘time’] datetime

  The time when the usage was requested.

• usage['cpu’] number

  The current cpu usage of the instance.

• usage['mem’] integer

  The current memory usage of the instance.

• usage['disk’] integer

  The current disk usage of the instance.

• host string

  The host the instance is running on.

• instance_ports object

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

• uptime integer

  The uptime in seconds for the instance.

• mem_quota integer

  The maximum memory the instance is allowed to use.

• disk_quota integer

  The maximum disk the instance is allowed to use.

• fds_quota integer

  The maximum file descriptors the instance is allowed to use.

Get a process

Definition

GET /v3/processes/:guid HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/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": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
      "method": "PUT"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "/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.[your-domain.com]/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.[your-domain.com]/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": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
      "method": "PUT"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

This endpoint updates an existing process.

Body Parameters

• command optional

  The command that will be used to start the process.

• ports optional

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

• health_check optional

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

Scale a process

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
      "method": "PUT"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

This endpoint scales an existing process.

Body Parameters

• instances optional

  The number of instances.

• memory_in_mb optional

  The memory in mb allocated per instance.

• disk_in_mb optional

  The disk in mb allocated per instance.

Terminate a process instance

Definition

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

Example Request

curl "https://api.[your-domain.com]/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.[your-domain.com]/v3/processes \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "/v3/processes?page=1&per_page=2"
    },
    "last": {
      "href": "/v3/processes?page=2&per_page=2"
    },
    "next": {
      "href": "/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": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
        },
        "scale": {
          "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
          "method": "PUT"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "/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": "/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
        },
        "scale": {
          "href": "/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/scale",
          "method": "PUT"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

This endpoint retrieves the processes the user has access to.

Query Parameters

• app_guids optional string

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

• guids optional string

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

• organization_guids optional string

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

• space_guids optional string

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

• types optional string

  Comma-delimited list of process types to filter by.

• page optional

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

• per_page optional

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

• order_by optional

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

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

• guid string

  Unique GUID for the process.

• type string

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

• command string

  The command is used to start the process.

• instances integer

  The number of instances to run.

• memory_in_mb integer

  The memory in mb allocated per instance.

• disk_in_mb integer

  The disk in mb allocated per instance.

• ports array of integers

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

• health_check health_check object

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

• created_at datetime

  The time with zone when the app was created.

• updated_at datetime

  The time with zone with the package was last updated.

• links object

  Links to related resources.

The health_check object

• type string

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

• data[‘timeout’] integer

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

The process stats object

• type string

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

• index integer

  The zero-based index of running intances.

• state string

  The state of the instance. RUNNING, CRASHED, STARTING

• usage[‘time’] datetime

  The time when the usage was requested.

• usage['cpu’] number

  The current cpu usage of the instance.

• usage['mem’] integer

  The current memory usage of the instance.

• usage['disk’] integer

  The current disk usage of the instance.

• host string

  The host the instance is running on.

• instance_ports object

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

• uptime integer

  The uptime in seconds for the instance.

• mem_quota integer

  The maximum memory the instance is allowed to use.

• disk_quota integer

  The maximum disk the instance is allowed to use.

• fds_quota integer

  The maximum file descriptors the instance is allowed to use.

Get a process for an app

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
      "method": "PUT"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "/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.[your-domain.com]/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.[your-domain.com]/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": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
    },
    "scale": {
      "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
      "method": "PUT"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "space": {
      "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
    },
    "stats": {
      "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats"
    }
  }
}

This endpoint scales an existing process belonging to an app.

Body Parameters

• instances optional

  The number of instances.

• memory_in_mb optional

  The memory in mb allocated per instance.

• disk_in_mb optional

  The disk in mb allocated per instance.

Terminate a process instance for an app

Definition

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

Example Request

curl "https://api.[your-domain.com]/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.[your-domain.com]/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": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=1&per_page=2"
    },
    "last": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2"
    },
    "next": {
      "href": "/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": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82"
        },
        "scale": {
          "href": "/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/scale",
          "method": "PUT"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "/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": "/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb"
        },
        "scale": {
          "href": "/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/scale",
          "method": "PUT"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "space": {
          "href": "/v2/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576"
        },
        "stats": {
          "href": "/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats"
        }
      }
    }
  ]
}

This endpoint retrieves the processes belonging to an app.

Query Parameters

• app_guids optional string

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

• guids optional string

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

• organization_guids optional string

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

• space_guids optional string

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

• types optional string

  Comma-delimited list of process types to filter by.

• page optional

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

• per_page optional

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

• order_by optional

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

Route Mappings

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

The route_mapping object

• guid string

  Unique GUID for the route mapping.

• app_port integer

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

• created_at datetime

  The time with zone when the app was created.

• updated_at datetime

  The time with zone with the package was last updated.

• links object

  Links to related resources.

Create a route mapping

Definition

POST /v3/route_mappings HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "route": {
      "href": "/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
    },
    "process": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/web"
    }
  }
}

This endpoint creates a new route mapping.

Body Parameters

• app_port optional

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

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

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

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

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

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

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

Get a route mapping

Definition

GET /v3/route_mappings/:guid HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "route": {
      "href": "/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
    },
    "process": {
      "href": "/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.[your-domain.com]/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.[your-domain.com]/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": "/v3/route_mappings?page=1&per_page=2"
    },
    "last": {
      "href": "/v3/route_mappings?page=2&per_page=2"
    },
    "next": {
      "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "route": {
          "href": "/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
        },
        "process": {
          "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/route_mappings/9f4970a8-9e6f-4984-b0a5-5e4a8af91665"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "route": {
          "href": "/v2/routes/a32332f0-fb30-4e9e-9b78-348b8b6b98b6"
        },
        "process": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes/admin-web"
        }
      }
    }
  ]
}

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

Query Parameters

• app_guids optional string

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

• route_guids optional string

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

• page optional

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

• per_page optional

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

• order_by optional

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

List route mappings for an app

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/route_mappings?page=1&per_page=2"
    },
    "last": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/route_mappings?page=2&per_page=2"
    },
    "next": {
      "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/route_mappings/89323d4e-2e84-43e7-83e9-adbf50a20c0e"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "route": {
          "href": "/v2/routes/9612ecbd-36f1-4ada-927a-efae9310b3a1"
        },
        "process": {
          "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/route_mappings/9f4970a8-9e6f-4984-b0a5-5e4a8af91665"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "route": {
          "href": "/v2/routes/a32332f0-fb30-4e9e-9b78-348b8b6b98b6"
        },
        "process": {
          "href": "/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

• guid string

  Unique GUID for the service binding

• type string

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

• data object

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

• created_at datetime

  The time with zone when the app was created.

• updated_at datetime

  The time with zone with the package was last updated.

• links object

  Links to related resources.

Create a service binding

Definition

POST /v3/service_bindings HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
    }
  }
}

This endpoint creates a new service binding.

Body Parameters

• type required

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

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

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

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

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

• data['parameters’] optional

  Additional configuration parameters for the service binding.

Get a service binding

Definition

GET /v3/service_bindings/:guid HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/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": null,
  "links": {
    "self": {
      "href": "/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
    },
    "service_instance": {
      "href": "/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
    },
    "app": {
      "href": "/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.[your-domain.com]/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.[your-domain.com]/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": "/v3/service_bindings?page=1&per_page=2"
    },
    "last": {
      "href": "/v3/service_bindings?page=2&per_page=2"
    },
    "next": {
      "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/service_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3"
        },
        "service_instance": {
          "href": "/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e"
        },
        "app": {
          "href": "/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": null,
      "links": {
        "self": {
          "href": "/v3/service_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62"
        },
        "service_instance": {
          "href": "/v3/service_instances/8bf356j3-9e18-45b1-3333-124163f31f9e"
        },
        "app": {
          "href": "/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13"
        }
      }
    }
  ]
}

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

Query Parameters

• app_guids optional string

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

• service_instance_guids optional string

  Comma-delimited list of service_instance_guids types to filter by. Example: service_instance_guids=guid1,guid2

• page optional

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

• per_page optional

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

• order_by optional

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

Tasks

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

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

The task object

• guid string

  Unique GUID for the task

• name string

  User-facing name of the task.

• command string

  Command that will be executed

• environment_variables string

  Environment variables set on the container running your task.

• memory_in_mb integer

  Maximum memory for the task in MB.

• state string

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

• droplet_guid string

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

• result object

  Results from the task

• result[failure_reason] string

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

• created_at datetime

  The time with zone when the app was created.

• updated_at datetime

  The time with zone with the package was last updated.

• links object

  Links to related resources.

Create a task

Definition

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

Example Request

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

Example Response

HTTP/1.1 202 Accepted

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "environment_variables": {},
  "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": "/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "droplet": {
      "href": "/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

This endpoint creates a new task.

Environment variables specified in the request body will overwrite and be appended to the environment variables set on the app associated with your task. These overwrite and are appended to the app’s running environment variable group.

Body Parameters

• name required

  User-facing name of the task

• command required

  Command that will be executed

• environment_variables optional

  Environment variables passed to the container running your task.

• memory_in_mb optional

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

• droplet_guid optional

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

Get a task

Definition

GET /v3/tasks/:guid HTTP/1.1

Example Request

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

Example Response

HTTP/1.1 200 OK

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "RUNNING",
  "memory_in_mb": 512,
  "environment_variables": {},
  "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": "/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "droplet": {
      "href": "/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
    }
  }
}

This endpoint retrieves a specific task.

Body Parameters

No arguments

Cancel a task

Definition

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

Example Request

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

Example Response

HTTP/1.1 202 Accepted

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "CANCELING",
  "memory_in_mb": 512,
  "environment_variables": {},
  "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": "/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "droplet": {
      "href": "/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.[your-domain.com]/v3/tasks" \
  -X GET \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 200 OK

{
  "pagination": {
    "total_results": 3,
    "total_pages": 2,
    "first": {
      "href": "/v3/tasks?page=1&per_page=2"
    },
    "last": {
      "href": "/v3/tasks?page=2&per_page=2"
    },
    "next": {
      "href": "/v3/tasks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "name": "hello",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "state": "SUCCEEDED",
      "memory_in_mb": 512,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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": "/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "droplet": {
          "href": "/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
    {
      "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
      "name": "migrate",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "state": "FAILED",
      "memory_in_mb": 512,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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": "/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "droplet": {
          "href": "/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
  ]
}

This endpoint retrieves the tasks the user has access to.

Query Parameters

• app_guids optional string

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

• names optional string

  Comma-delimited list of task names to filter by.

• guids optional string

  Comma-delimited list of task guids to filter by.

• organization_guids optional string

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

• space_guids optional string

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

• states optional string

  Comma-delimited list of task states to filter by.

• page optional

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

• per_page optional

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

• order_by optional

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

Cancel a task for an app

Definition

PUT /v3/apps/:guid/tasks/:guid/cancel HTTP/1.1

Example Request

curl "https://api.[your-domain.com]/v3/apps/[guid]/tasks/[guid]/cancel" \
  -X PUT \
  -H "Authorization: bearer [token]"

Example Response

HTTP/1.1 202 Accepted

{
  "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
  "name": "migrate",
  "command": "rake db:migrate",
  "state": "CANCELING",
  "memory_in_mb": 512,
  "environment_variables": {},
  "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": "/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
    },
    "app": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
    },
    "droplet": {
      "href": "/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 for an app

Definition

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

Example Request

curl "https://api.[your-domain.com]/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": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=1&per_page=2"
    },
    "last": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
    },
    "next": {
      "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2"
    },
    "previous": null
  },
  "resources": [
    {
      "guid": "d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa",
      "name": "hello",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "state": "SUCCEEDED",
      "memory_in_mb": 512,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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": "/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "droplet": {
          "href": "/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
    {
      "guid": "63b4cd89-fd8b-4bf1-a311-7174fcc907d6",
      "name": "migrate",
      "command": "[PRIVATE DATA HIDDEN IN LISTS]",
      "state": "FAILED",
      "memory_in_mb": 512,
      "environment_variables": {
        "redacted_message": "[PRIVATE DATA HIDDEN IN LISTS]"
      },
      "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": "/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6"
        },
        "app": {
          "href": "/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5"
        },
        "droplet": {
          "href": "/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a"
        }
      }
    },
  ]
}

This endpoint retrieves the tasks the user has access to.

Query Parameters

• guids optional string

  Comma-delimited list of task guids to filter by.

• names optional string

  Comma-delimited list of task names to filter by.

• states optional string

  Comma delimited list of task states to filter by.

• page optional

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

• per_page optional

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

• order_by optional

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