API docs by Redocly

Cloud Foundry V3 API (3.1.0)

Download OpenAPI specification:

License: Apache 2.0

Welcome to the Cloud Foundry V3 API docs! Version 3 adds 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
  • Changing application source code without stopping the app via deployments

Getting help

The CAPI team can most easily be reached on our Slack channel for questions and issues regarding the API. To report an issue with the docs or API, please feel free to file a GitHub issue on our API repo, cloud_controller_ng. We recommend reaching out to Slack first as we will be most responsive there.

More resources

  • The Cloud Foundry V2 API is still depricated but still available for interacting with Cloud Foundry.
  • Running Tasks
  • V3 API Documentation OpenAPI Spec Source Code.

Apps

Apps represent the core entities in the Cloud Foundry environment. They are the deployable units that run your code. Each app can have multiple processes, routes, and services associated with it. Apps can be scaled horizontally by increasing the number of instances. They can also be updated and restarted as needed. The lifecycle of an app includes stages such as staging, starting, running, and stopping. Apps can be managed through various endpoints that allow for creation, updating, deletion, and retrieval of app details.

List apps

Retrieve all apps the user has access to.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
guids
Array of strings

Comma-delimited list of app GUIDs to filter by

names
Array of strings

Comma-delimited list of app names to filter by

space_guids
Array of strings

Comma-delimited list of space GUIDs to filter by

organization_guids
Array of strings

Comma-delimited list of organization GUIDs to filter by

stacks
Array of strings

Comma-delimited list of stack names to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create an app

Create a new app.

Authorizations:
oauth
Request Body schema: application/json
required

App object that needs to be created

name
required
string

The name of the app

relationships
required
object (relationships)

Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not.

Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not.

Not all resources implement every relationship operation demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships.

Endpoints that return relationship data list this information under the relationships key.

The relationship object The relationship object is a key-value pair that uniquely identifies a resource. In practice this is almost always the guid of a resource.

object (lifecycle)

The lifecycle type defines how the application droplet is created and run. The following lifecycle types are supported: - buildpack: Traditional buildpacks for Cloud Foundry applications. - cnb: Cloud Native Buildpacks that are OCI-compliant. - docker: Run pre-built Docker images.

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "relationships": { },
  • "lifecycle": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "state": "string",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Retrieve an app

Retrieve details of a specific app by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "state": "string",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Update an app

Update attributes of a specific app by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

App object that needs to be updated

name
required
string

The name of the app

object (lifecycle)

The lifecycle type defines how the application droplet is created and run. The following lifecycle types are supported: - buildpack: Traditional buildpacks for Cloud Foundry applications. - cnb: Cloud Native Buildpacks that are OCI-compliant. - docker: Run pre-built Docker images.

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "lifecycle": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "state": "string",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Delete an app

Delete a specific app by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Start an app

Start a specific app by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "state": "string",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Stop an app

Stop a specific app by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "state": "string",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Restart an app

Stop and then start a specific app by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "state": "string",
  • "lifecycle": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Get current droplet for an app

Retrieve the current droplet for an app by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "state": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

Set the current droplet for an app

Set the current droplet for an app by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

Droplet relationship object that needs to be set

required
object (relationship)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc"
}

AppFeatures

AppFeatures provide additional capabilities and configurations for apps. These features can include things like auto-scaling, health checks, and custom domains. AppFeatures enhance the functionality of apps by allowing developers to enable or disable specific features based on their requirements. They can be managed through endpoints that allow for enabling, disabling, and retrieving the status of app features.

List app features

Retrieve a list of features for a specific app.

Authorizations:
oauth
path Parameters
app_guid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Update app feature

Update the status of a specific feature for a given app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>
feature_name
required
string

The name of the app feature

Request Body schema: application/json
required

App feature object that needs to be updated

enabled
boolean

Whether the app feature should be enabled

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "enabled": true
}

AppUsageEvents

AppUsageEvents track the usage and activity of apps within the Cloud Foundry environment. These events provide insights into app lifecycle changes, such as creation, deletion, scaling, and crashes. AppUsageEvents are useful for monitoring and auditing purposes, helping administrators understand how apps are being used and identify any issues. They can be retrieved through endpoints that provide detailed information about each event.

List app usage events

Retrieve all app usage events the user has access to.

Authorizations:
oauth
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

after_guid
string

Filters out events before and including the event with the given guid.

guids
Array of strings

Comma-delimited list of usage event guids to filter by.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get an app usage event

Retrieve a specific app usage event by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "state": {
    },
  • "app": {
    },
  • "process": {
    },
  • "space": {
    },
  • "organization": {
    },
  • "buildpack": {
    },
  • "task": {
    },
  • "memory_in_mb_per_instance": {
    },
  • "instance_count": {
    },
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    }
}

Purge and seed app usage events

Destroys all existing events. Populates new usage events, one for each started app. All populated events will have a created_at value of current time. There is the potential race condition if apps are currently being started, stopped, or scaled. The seeded usage events will have the same guid as the app.

Authorizations:
oauth

Responses

AuditEvents

AuditEvents capture significant actions and changes within the Cloud Foundry environment. These events include actions performed by users, such as creating, updating, or deleting resources. AuditEvents provide a comprehensive audit trail that helps administrators track changes and ensure compliance with organizational policies. They can be retrieved through endpoints that provide detailed information about each event, including the user who performed the action and the affected resources.

List audit events

Retrieve a list of all audit events the user has access to.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

entity_type
string

The type of the entity involved in the audit event. This can be used to filter audit events by the entity involved. For example, filtering by type can return audit events involving only apps, spaces, or organizations.

type
string

The type of the audit event

target_guids
Array of strings

Comma-delimited list of target GUIDs to filter by.

space_guids
Array of strings

Comma-delimited list of space GUIDs to filter by.

organization_guids
Array of strings

Comma-delimited list of organization GUIDs to filter by.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create an audit event

Create a new audit event.

Authorizations:
oauth
Request Body schema: application/json
required

Audit event object that needs to be created

type
string

The type of the event

object
object
data
object

Additional information about the event

object
object
object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "actor": {
    },
  • "target": {
    },
  • "data": { },
  • "space": {
    },
  • "organization": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "type": "string",
  • "actor": {
    },
  • "target": {
    },
  • "data": { },
  • "space": {
    },
  • "organization": {
    }
}

Retrieve an audit event

Retrieve details of a specific audit event by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "type": "string",
  • "actor": {
    },
  • "target": {
    },
  • "data": { },
  • "space": {
    },
  • "organization": {
    }
}

Builds

Builds represent the process of transforming source code into a runnable artifact. In Cloud Foundry, builds are created using buildpacks, which provide the necessary dependencies and configurations for the app. Builds can be triggered manually or automatically as part of the app deployment process. They can be managed through endpoints that allow for creation, updating, deletion, and retrieval of build details.

List builds

Retrieve a list of all builds the user has access to.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
app_guids
Array of strings

Comma-delimited list of app GUIDs to filter by

package_guids
Array of strings

Comma-delimited list of package GUIDs to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a build

Create a new build.

Authorizations:
oauth
Request Body schema: application/json
required

Build object that needs to be created

required
object (relationship)
object (lifecycle)

The lifecycle type defines how the application droplet is created and run. The following lifecycle types are supported: - buildpack: Traditional buildpacks for Cloud Foundry applications. - cnb: Cloud Native Buildpacks that are OCI-compliant. - docker: Run pre-built Docker images.

staging_memory_in_mb
integer

Memory in MB allocated for staging of the build

staging_disk_in_mb
integer

Disk space in MB allocated for staging of the build

staging_log_rate_limit_bytes_per_second
integer

Log rate limit in bytes per second allocated for staging of the build

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "package": {
    },
  • "lifecycle": {
    },
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "state": "string",
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "error": "string",
  • "lifecycle": {
    },
  • "checksum": {
    },
  • "metadata": {
    },
  • "relationships": { },
  • "droplet": {
    },
  • "created_by": {
    }
}

Retrieve a build

Retrieve details of a specific build by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "state": "string",
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "error": "string",
  • "lifecycle": {
    },
  • "checksum": {
    },
  • "metadata": {
    },
  • "relationships": { },
  • "droplet": {
    },
  • "created_by": {
    }
}

Update a build

Update attributes of a specific build by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

Build object that needs to be updated

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "state": "string",
  • "staging_memory_in_mb": 0,
  • "staging_disk_in_mb": 0,
  • "staging_log_rate_limit_bytes_per_second": 0,
  • "error": "string",
  • "lifecycle": {
    },
  • "checksum": {
    },
  • "metadata": {
    },
  • "relationships": { },
  • "droplet": {
    },
  • "created_by": {
    }
}

Delete a build

Delete a specific build by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List builds for an app

Retrieve a list of builds for a specific app.

Authorizations:
oauth
path Parameters
app_guid
required
string <uuid>
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
app_guids
Array of strings

Comma-delimited list of app GUIDs to filter by

package_guids
Array of strings

Comma-delimited list of package GUIDs to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Buildpacks

Buildpacks are responsible for detecting, compiling, and packaging apps in the Cloud Foundry environment. They provide the necessary runtime and dependencies for the app to run. Buildpacks can be customized and extended to support different languages and frameworks. They can be managed through endpoints that allow for creation, updating, deletion, and retrieval of buildpack details.

Create a buildpack

Create a new buildpack

Authorizations:
oauth
Request Body schema: application/json
required

Buildpack object that needs to be added

name
required
string

The name of the buildpack

stack
string

The stack the buildpack is compatible with

position
integer

The position of the buildpack in the order of execution

state
string
Enum: "AWAITING_UPLOAD" "READY"

The state of the buildpack

enabled
boolean

Whether the buildpack is enabled

locked
boolean

Whether the buildpack is locked

filename
string

The filename of the buildpack

Responses

Request samples

Content type
application/json
{
  • "name": "ruby_buildpack",
  • "stack": "cflinuxfs3",
  • "position": 1,
  • "enabled": true,
  • "state": "AWAITING_UPLOAD",
  • "locked": false,
  • "filename": "ruby_buildpack-cflinuxfs3-v1.0.0.zip"
}

Response samples

Content type
application/json
{}

List buildpacks

Retrieve a list of buildpacks available in the system.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
name
Array of strings

Comma-delimited list of buildpack names to filter by

stacks
Array of strings

Comma-delimited list of stacks to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Retrieve a buildpack

Retrieve details of a specific buildpack by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{}

Update a buildpack

Update attributes of a specific buildpack by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

Buildpack object that needs to be updated

name
required
string

The name of the buildpack

stack
string

The stack the buildpack is compatible with

position
integer

The position of the buildpack in the order of execution

enabled
boolean

Whether the buildpack is enabled

locked
boolean

Whether the buildpack is locked

filename
string

The filename of the buildpack

Responses

Request samples

Content type
application/json
{
  • "name": "ruby_buildpack",
  • "stack": "cflinuxfs3",
  • "position": 1,
  • "enabled": true,
  • "locked": false,
  • "filename": "ruby_buildpack-cflinuxfs3-v1.0.0.zip"
}

Response samples

Content type
application/json
{}

Delete a buildpack

Delete a specific buildpack by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Upload a buildpack

Upload a buildpack file for a specific buildpack by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: multipart/form-data
required

The buildpack file to be uploaded

bits
required
string <binary>

The buildpack file to be uploaded

Responses

Response samples

Content type
application/json
{}

Deployments

Deployments represent the process of deploying apps to the Cloud Foundry environment. They include stages such as staging, starting, and running the app. Deployments can be triggered manually or automatically as part of the app lifecycle. They can be managed through endpoints that allow for creation, updating, deletion, and retrieval of deployment details.

List deployments

Retrieve a list of all deployments the user has access to.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
app_guids
Array of strings

Comma-delimited list of app GUIDs to filter by

states
Array of strings

Comma-delimited list of deployment states to filter by

status_reasons
Array of strings

Comma-delimited list of status reasons to filter by; valid values include DEPLOYING, PAUSED, CANCELING, DEPLOYED, CANCELED, SUPERSEDED

status_values
Array of strings

Comma-delimited list of status values to filter by; valid values include ACTIVE and FINALIZED

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a deployment

Create a new deployment.

Authorizations:
oauth
Request Body schema: application/json
required

Deployment object that needs to be created

relationships
object (relationships)

Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not.

Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not.

Not all resources implement every relationship operation demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships.

Endpoints that return relationship data list this information under the relationships key.

The relationship object The relationship object is a key-value pair that uniquely identifies a resource. In practice this is almost always the guid of a resource.

strategy
string
object (relationship)
object (relationship)
object
object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "relationships": { },
  • "strategy": "string",
  • "droplet": {
    },
  • "revision": {
    },
  • "options": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "status": {
    },
  • "strategy": "string",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Retrieve a deployment

Retrieve details of a specific deployment by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "status": {
    },
  • "strategy": "string",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Update a deployment

Update attributes of a specific deployment by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

Deployment object that needs to be updated

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "status": {
    },
  • "strategy": "string",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Delete a deployment

Delete a specific deployment by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Cancel a deployment

Cancel a deployment in progress.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "status": {
    },
  • "strategy": "string",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Continue a deployment

Continue a paused deployment.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "status": {
    },
  • "strategy": "string",
  • "options": {
    },
  • "droplet": {
    },
  • "previous_droplet": {
    },
  • "new_processes": [
    ],
  • "revision": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Domains

Domains represent the DNS domains used to route traffic to apps in the Cloud Foundry environment. They can be shared or private, and can be associated with specific organizations or spaces. Domains can be managed through endpoints that allow for creation, updating, deletion, and retrieval of domain details.

List domains

Retrieve a list of all domains the user has access to.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
guids
Array of strings

Comma-delimited list of GUIDs to filter by

names
Array of strings

Comma-delimited list of domain names to filter by

organization_guids
Array of strings

Comma-delimited list of owning organization GUIDs to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a domain

Create a new domain.

Authorizations:
oauth
Request Body schema: application/json
required

Domain object that needs to be created

name
required
string

The name of the domain

internal
required
boolean

Whether the domain is used for internal (container-to-container) traffic

object
object (relationshipToOne)

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

object (relationshipToMany)

Some relationships relate a resource to several other resources. For example, an isolation segment can be entitled to multiple organizations.

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "internal": true,
  • "router_group": {
    },
  • "organization": {
    },
  • "shared_organizations": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "internal": true,
  • "router_group": {
    },
  • "supported_protocols": [
    ],
  • "relationships": { },
  • "metadata": {
    }
}

Retrieve a domain

Retrieve details of a specific domain by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "internal": true,
  • "router_group": {
    },
  • "supported_protocols": [
    ],
  • "relationships": { },
  • "metadata": {
    }
}

Update a domain

Update attributes of a specific domain by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

Domain object that needs to be updated

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "internal": true,
  • "router_group": {
    },
  • "supported_protocols": [
    ],
  • "relationships": { },
  • "metadata": {
    }
}

Delete a domain

Delete a specific domain by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Share a domain

Share an organization-scoped domain to other organizations specified by a list of organization GUIDs.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

List of organizations to share the domain with

Array of objects (relationship)

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Unshare a domain

Unshare a domain from a specific organization.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

org_guid
required
string <uuid>

The GUID of the organization to unshare the domain from

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List domains for an organization

Retrieve a list of all domains available in an organization for the current user.

Authorizations:
oauth
path Parameters
org_guid
required
string <uuid>
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

guids
Array of strings

Comma-delimited list of GUIDs to filter by

names
Array of strings

Comma-delimited list of domain names to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get the default domain

Retrieve the default domain for a given organization.

Authorizations:
oauth
path Parameters
org_guid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "internal": true,
  • "router_group": {
    },
  • "supported_protocols": [
    ],
  • "relationships": { },
  • "metadata": {
    }
}

Droplets

Droplets are the runnable artifacts created from builds in the Cloud Foundry environment. They contain the compiled code and dependencies needed to run the app. Droplets can be managed through endpoints that allow for creation, updating, deletion, and retrieval of droplet details.

Create a droplet

Create a new droplet

Authorizations:
oauth
Request Body schema: application/json
required

Droplet object that needs to be created

relationships
required
object (relationships)

Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not.

Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not.

Not all resources implement every relationship operation demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships.

Endpoints that return relationship data list this information under the relationships key.

The relationship object The relationship object is a key-value pair that uniquely identifies a resource. In practice this is almost always the guid of a resource.

process_types
object

Process names and start commands for the droplet

Responses

Request samples

Content type
application/json
{
  • "relationships": { },
  • "process_types": { }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "state": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

List droplets

Retrieve a list of droplets available in the system.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
guids
Array of strings

Comma-delimited list of droplet GUIDs to filter by

states
Array of strings

Comma-delimited list of droplet states to filter by

app_guids
Array of strings

Comma-delimited list of app GUIDs to filter by

space_guids
Array of strings

Comma-delimited list of space GUIDs to filter by

organization_guids
Array of strings

Comma-delimited list of organization GUIDs to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Retrieve a droplet

Retrieve details of a specific droplet by its GUID.

Authorizations:
oauth
path Parameters
droplet_guid
required
string <uuid>

The GUID of the droplet

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "state": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

Update a droplet

Update attributes of a specific droplet by its GUID.

Authorizations:
oauth
path Parameters
droplet_guid
required
string <uuid>

The GUID of the droplet

Request Body schema: application/json
required

Droplet object that needs to be updated

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

image
required
string

Image reference where the built complete image was stored

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "image": "string"
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "state": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

Delete a droplet

Delete a specific droplet by its GUID.

Authorizations:
oauth
path Parameters
droplet_guid
required
string <uuid>

The GUID of the droplet

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Download a droplet

Download a droplet file by its GUID.

Authorizations:
oauth
path Parameters
droplet_guid
required
string <uuid>

The GUID of the droplet

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Upload a droplet

Upload a droplet file for a specific droplet by its GUID.

Authorizations:
oauth
path Parameters
droplet_guid
required
string <uuid>

The GUID of the droplet

Request Body schema: multipart/form-data
required

The droplet file to be uploaded

bits
required
string <binary>

The droplet file to be uploaded

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "state": "string",
  • "error": "string",
  • "lifecycle": {
    },
  • "execution_metadata": "string",
  • "process_types": { },
  • "metadata": {
    },
  • "checksum": {
    },
  • "buildpacks": [
    ],
  • "stack": "string",
  • "image": "string"
}

EnvironmentVariableGroups

EnvironmentVariableGroups represent collections of environment variables that can be applied to apps in the Cloud Foundry environment. They provide a way to manage and share common configurations across multiple apps. EnvironmentVariableGroups can be managed through endpoints that allow for creation, updating, deletion, and retrieval of environment variable group details.

Get running environment variable group

Retrieve the environment variable group for running applications.

Authorizations:
oauth

Responses

Response samples

Content type
application/json
{
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "var": {
    },
  • "links": { }
}

Update running environment variable group

Update the environment variable group for running applications.

Authorizations:
oauth
Request Body schema: application/json
required

The environment variables to update

object

Environment variables to inject; keys and values must be strings

Responses

Request samples

Content type
application/json
{
  • "var": {
    }
}

Response samples

Content type
application/json
{
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "var": {
    },
  • "links": { }
}

Get staging environment variable group

Retrieve the environment variable group for staging applications.

Authorizations:
oauth

Responses

Response samples

Content type
application/json
{
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "var": {
    },
  • "links": { }
}

Update staging environment variable group

Update the environment variable group for staging applications.

Authorizations:
oauth
Request Body schema: application/json
required

The environment variables to update

object

Environment variables to inject; keys and values must be strings

Responses

Request samples

Content type
application/json
{
  • "var": {
    }
}

Response samples

Content type
application/json
{
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "var": {
    },
  • "links": { }
}

FeatureFlags

FeatureFlags provide a way to enable or disable specific features in the Cloud Foundry environment. They allow administrators to control the availability of features based on organizational requirements. FeatureFlags can be managed through endpoints that allow for enabling, disabling, and retrieving the status of feature flags.

List feature flags

Retrieve a list of all feature flags.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a feature flag

Create a new feature flag.

Authorizations:
oauth
Request Body schema: application/json
required

Feature flag object that needs to be created

name
required
string

The name of the feature flag

enabled
required
boolean

Whether the feature flag is enabled

custom_error_message
string

The error string returned by the API when a client performs an action disabled by the feature flag

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "custom_error_message": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "custom_error_message": "string",
  • "links": { }
}

Retrieve a feature flag

Retrieve details of a specific feature flag by its name.

Authorizations:
oauth
path Parameters
name
required
string

The name of the feature flag

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "custom_error_message": "string",
  • "links": { }
}

Update a feature flag

Update the properties of a specific feature flag by its name.

Authorizations:
oauth
path Parameters
name
required
string

The name of the feature flag

Request Body schema: application/json
required

Feature flag object that needs to be updated

enabled
boolean

Whether the feature flag is enabled

custom_error_message
string

The error string returned by the API when a client performs an action disabled by the feature flag

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "custom_error_message": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "custom_error_message": "string",
  • "links": { }
}

Info

The Info endpoint provides information about the Cloud Foundry environment, including version details, API endpoints, and other metadata. It is useful for understanding the capabilities and configuration of the environment. The Info endpoint can be accessed to retrieve detailed information about the Cloud Foundry deployment.

Get platform info

Returns information about the platform.

Authorizations:
oauth

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "build": "string",
  • "version": 0,
  • "description": "string",
  • "cli_version": {
    },
  • "custom": {
    },
  • "links": {
    }
}

Get platform usage summary

This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation.

Authorizations:
oauth

Responses

Response samples

Content type
application/json
{
  • "usage_summary": {
    },
  • "links": {
    }
}

IsolationSegments

IsolationSegments provide a way to isolate apps and resources within the Cloud Foundry environment. They allow for the creation of isolated environments with dedicated resources, such as compute, storage, and networking. IsolationSegments can be managed through endpoints that allow for creation, updating, deletion, and retrieval of isolation segment details.

List isolation segments

Retrieve all isolation segments the user has access to.

Authorizations:
oauth
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
guids
Array of strings

Comma-delimited list of isolation segment guids to filter by.

names
Array of strings

Comma-delimited list of isolation segment names to filter by.

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create an isolation segment

Create a new isolation segment.

Authorizations:
oauth
Request Body schema: application/json
required

Isolation Segment to create

name
required
string

The name of the isolation segment

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "metadata": {
    }
}

Get an isolation segment

Retrieve a specific isolation segment by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "metadata": {
    }
}

Update an isolation segment

Update a specific isolation segment by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

Isolation segment to update

name
string

The name of the isolation segment

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "metadata": {
    }
}

Delete an isolation segment

Delete a specific isolation segment by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "operation": "string",
  • "state": "PROCESSING",
  • "errors": [
    ],
  • "warnings": [
    ]
}

Entitle organizations for isolation segment

This endpoint entitles the specified organizations for the isolation segment. In the case where the specified isolation segment is the system-wide shared segment, and if an organization is not already entitled for any other isolation segment, then the shared isolation segment automatically gets assigned as the default for that organization.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

List of organizations to entitle

Array of objects (relationship)

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List organizations

List all organizations entitled to the isolation segment.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Revoke entitlement of an organization

Revoke the entitlement of an organization for an isolation segment.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

org_guid
required
string <uuid>

The GUID of the organization to revoke entitlement from.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List spaces

List all spaces assigned to the isolation segment.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Jobs

Jobs represent asynchronous operations in the Cloud Foundry environment. They are used for tasks that may take a long time to complete, such as app deployments, service provisioning, and data migrations. Jobs can be managed through endpoints that allow for creation, updating, deletion, and retrieval of job details.

Get a job

Retrieve a specific job by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "operation": "string",
  • "state": "PROCESSING",
  • "errors": [
    ],
  • "warnings": [
    ]
}

List jobs

Retrieve a list of all jobs the user has access to.

Authorizations:
oauth
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
guids
Array of strings

Comma-delimited list of job guids to filter by

states
Array of strings

Comma-delimited list of job states to filter by

operations
Array of strings

Comma-delimited list of operation types to filter by

resource_guids
Array of strings

Comma-delimited list of resource guids to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Manifests

Manifests provide a way to define the configuration and deployment details of apps in the Cloud Foundry environment. They include information such as app name, buildpack, environment variables, and services. Manifests can be used to automate the deployment and management of apps. They can be managed through endpoints that allow for creation, updating, deletion, and retrieval of manifest details.

Organizations

Organizations represent the top-level entities in the Cloud Foundry environment. They provide a way to group and manage resources, such as apps, spaces, and users. Organizations can be managed through endpoints that allow for creation, updating, deletion, and retrieval of organization details.

OrganizationQuotas

OrganizationQuotas define the resource limits and constraints for organizations in the Cloud Foundry environment. They include limits on memory, instances, routes, and services. OrganizationQuotas can be managed through endpoints that allow for creation, updating, deletion, and retrieval of organization quota details.

Packages

Packages represent the source code and dependencies of apps in the Cloud Foundry environment. They are used to create builds and droplets. Packages can be managed through endpoints that allow for creation, updating, deletion, and retrieval of package details.

List packages

Retrieve a list of all packages the user has access to.

Authorizations:
oauth
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
guids
Array of strings

Comma-delimited list of package guids to filter by

states
Array of strings

Comma-delimited list of package states to filter by

types
Array of strings

Comma-delimited list of package types to filter by

app_guids
Array of strings

Comma-delimited list of app guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a package

Create a new package.

Authorizations:
oauth
Request Body schema: application/json
required

Package object that needs to be created

type
required
string
Enum: "bits" "docker"

Type of the package; valid values are bits or docker

object

Data for package type

relationships
required
object (relationships)

Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not.

Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not.

Not all resources implement every relationship operation demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships.

Endpoints that return relationship data list this information under the relationships key.

The relationship object The relationship object is a key-value pair that uniquely identifies a resource. In practice this is almost always the guid of a resource.

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "type": "bits",
  • "data": {
    },
  • "relationships": { },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "type": "bits",
  • "data": {
    },
  • "state": "AWAITING_UPLOAD",
  • "relationships": { },
  • "metadata": {
    }
}

Get a package

Retrieve a specific package by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "type": "bits",
  • "data": {
    },
  • "state": "AWAITING_UPLOAD",
  • "relationships": { },
  • "metadata": {
    }
}

Update a package

Update attributes of a specific package by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json
required

Package object that needs to be updated

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "type": "bits",
  • "data": {
    },
  • "state": "AWAITING_UPLOAD",
  • "relationships": { },
  • "metadata": {
    }
}

Delete a package

Delete a specific package by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "operation": "string",
  • "state": "PROCESSING",
  • "errors": [
    ],
  • "warnings": [
    ]
}

Upload package bits

Upload the bits for a specific package by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: multipart/form-data
required

The package bits to be uploaded

bits
required
string <binary>

A binary zip file containing the package bits

resources
Array of objects

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "type": "bits",
  • "data": {
    },
  • "state": "AWAITING_UPLOAD",
  • "relationships": { },
  • "metadata": {
    }
}

Download package bits

Download the bits for a specific package by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List packages for an app

Retrieve a list of packages for a specific app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
guids
Array of strings

Comma-delimited list of package guids to filter by

states
Array of strings

Comma-delimited list of package states to filter by

types
Array of strings

Comma-delimited list of package types to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Copy a package

Copy a package to a different app.

Authorizations:
oauth
query Parameters
source_guid
required
string <uuid>

The GUID of the package to copy from

Request Body schema: application/json
required

Destination app for the copied package

relationships
required
object (relationships)

Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not.

Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not.

Not all resources implement every relationship operation demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships.

Endpoints that return relationship data list this information under the relationships key.

The relationship object The relationship object is a key-value pair that uniquely identifies a resource. In practice this is almost always the guid of a resource.

Responses

Request samples

Content type
application/json
{
  • "relationships": { }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "type": "bits",
  • "data": {
    },
  • "state": "AWAITING_UPLOAD",
  • "relationships": { },
  • "metadata": {
    }
}

Processes

Processes represent the runnable units of apps in the Cloud Foundry environment. They include information such as command, instances, memory, and disk. Processes can be managed through endpoints that allow for creation, updating, deletion, and retrieval of process details.

ResourceMatches

ResourceMatches provide a way to identify and reuse existing resources in the Cloud Foundry environment. They help optimize resource usage by matching new resources with existing ones. ResourceMatches can be managed through endpoints that allow for creation, updating, deletion, and retrieval of resource match details.

Revisions

Revisions represent the versions of apps in the Cloud Foundry environment. They provide a way to track and manage changes to apps over time. Revisions can be managed through endpoints that allow for creation, updating, deletion, and retrieval of revision details.

List revisions for an app

Retrieve a list of revisions for a specific app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
versions
Array of integers

Filter by revision versions

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

List deployed revisions for an app

Retrieve a list of deployed revisions for a specific app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
versions
Array of integers

Filter by revision versions

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Get a revision

Retrieve a specific revision of an app by its version number.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

version
required
integer

The version number of the revision

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "version": 0,
  • "description": "string",
  • "droplet": {
    },
  • "relationships": {
    },
  • "enabled": true,
  • "metadata": {
    }
}

Update a revision

Update a revision of an app by its version number.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

version
required
integer

The version number of the revision

Request Body schema: application/json
required

Revision object that needs to be updated

description
string

Description of the revision

enabled
boolean

Whether the revision is enabled

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "enabled": true,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "version": 0,
  • "description": "string",
  • "droplet": {
    },
  • "relationships": {
    },
  • "enabled": true,
  • "metadata": {
    }
}

Get environment variables for a revision

Retrieve the environment variables associated with a specific revision of an app.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

version
required
integer

The version number of the revision

Responses

Response samples

Content type
application/json
{
  • "var": {
    },
  • "links": {
    }
}

Roles

Roles define the permissions and access levels for users in the Cloud Foundry environment. They include roles such as admin, developer, and auditor. Roles can be managed through endpoints that allow for creation, updating, deletion, and retrieval of role details.

List roles

Retrieve all roles the user has access to.

Authorizations:
oauth
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
guids
Array of strings

Comma-delimited list of role guids to filter by

types
Array of strings
Items Enum: "organization_user" "organization_auditor" "organization_manager" "organization_billing_manager" "space_auditor" "space_developer" "space_manager" "space_supporter"

Comma-delimited list of role types to filter by

organization_guids
Array of strings

Comma-delimited list of organization guids to filter by

space_guids
Array of strings

Comma-delimited list of space guids to filter by

user_guids
Array of strings

Comma-delimited list of user guids to filter by

include
Array of strings
Items Enum: "user" "space" "organization"

Optionally include additional related resources in the response; valid values are user, space, and organization.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a role

Create a new role.

Authorizations:
oauth
Request Body schema: application/json

Role to create

type
string
Enum: "organization_user" "organization_auditor" "organization_manager" "organization_billing_manager" "space_auditor" "space_developer" "space_manager" "space_supporter"

Role type

object

Responses

Request samples

Content type
application/json
{
  • "type": "organization_user",
  • "relationships": {
    }
}

Response samples

Content type
application/json
{
  • "type": "organization_user",
  • "relationships": {
    },
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    }
}

Get a role

Retrieve a specific role by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

query Parameters
include
Array of strings
Items Enum: "user" "space" "organization"

Optionally include additional related resources in the response; valid values are user, space, and organization.

Responses

Response samples

Content type
application/json
{
  • "type": "organization_user",
  • "relationships": {
    },
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    }
}

Delete a role

Delete a specific role by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Root

The Root endpoint provides the entry point for the Cloud Foundry API. It includes links to all the available resources and endpoints. The Root endpoint can be accessed to retrieve detailed information about the Cloud Foundry API and its capabilities.

Get root

The Root endpoint provides the entry point for the Cloud Foundry API. It includes links to all the available resources and endpoints.

Authorizations:
oauth

Responses

Response samples

Content type
application/json
{
  • "links": {
    }
}

Routes

Routes represent the network endpoints used to access apps in the Cloud Foundry environment. They include information such as domain, path, and port. Routes can be managed through endpoints that allow for creation, updating, deletion, and retrieval of route details. By specifying routes, applications can define how they are accessed by end-users, ensuring traffic is directed to the appropriate application instances.

Create a route

Create a new route

Authorizations:
oauth
Request Body schema: application/json
required

Route object that needs to be added

protocol
required
string

Protocol used by the route; valid values are http1, http2, and tcp

host
string

Hostname of the route; can be null for TCP routes

path
string

Path of the route; must start with a slash /.

port
integer

Port of the route; can be null if not specified

relationships
required
object (relationships)

Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not.

Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not.

Not all resources implement every relationship operation demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships.

Endpoints that return relationship data list this information under the relationships key.

The relationship object The relationship object is a key-value pair that uniquely identifies a resource. In practice this is almost always the guid of a resource.

Responses

Request samples

Content type
application/json
{
  • "protocol": "http1",
  • "host": "my-app",
  • "path": "/my-path",
  • "port": 8080,
  • "relationships": { }
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "protocol": "string",
  • "host": "string",
  • "path": "string",
  • "port": 0,
  • "url": "string",
  • "relationships": { },
  • "metadata": {
    }
}

List routes

Retrieve a list of routes available in the system.

Authorizations:
oauth
query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

label_selector
string

Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or more requirements in a comma-delimited list. The maximum number of requirements in a single selector is 50.

Example label selector: cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29

Selectors can be used to filter and group resources using the query parameter label_selector on list endpoints.

When included in a URL, the selector must be appropriately escaped.

A requirement consists of a key, an operator, and optional value(s).

Requirement Format Description
existence key Returns all resources that have been assigned a label with the given key (with any value)
non-existence !key Returns all resources that have not been assigned a label with the given key (with any value)
equality key=value or key==value Returns all resources that have been assigned a label with the given key and value
inequality key!=value Returns all resources that either have not been assigned a label with the given key or have a label with the given key but a different value
set inclusion key in (value1,value2…) Returns all resources that have been assigned a label with the given key with one of the specified value(s)
set exclusion key notin (value1,value2…) Returns all resources that either have not been assigned a label with the given key or have a label with the given key but none of the specified value(s)
protocols
Array of strings

Comma-delimited list of protocols to filter by

hosts
Array of strings

Comma-delimited list of hosts to filter by

paths
Array of strings

Comma-delimited list of paths to filter by

ports
Array of integers

Comma-delimited list of ports to filter by

domain_guids
Array of strings

Comma-delimited list of domain GUIDs to filter by

space_guids
Array of strings

Comma-delimited list of space GUIDs to filter by

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "resources": [
    ]
}

List destinations for a route

Retrieve a list of destinations for a specific route by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "destinations": [
    ]
}

Insert destinations for a route

Insert destinations for a specific route by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json

Route destination to create

Array
required
object

App to which the route destination directs traffic. Must provide either app or service instance.

object

Service instance to which the route destination directs traffic. Must provide either app or service instance.

weight
integer

Weight of the destination. Routes will equally distribute the traffic to all destinations with the same weight.

port
integer

Port of the destination that receives traffic.

protocol
string
Enum: "http1" "http2"

Protocol of the destination that receives traffic. Defaults to 'http1' when not specified for HTTP routes, and is ignored for TCP routes.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "destinations": [
    ]
}

Replace all destinations for a route

Replace all destinations for a specific route by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json

Route destination to create

Array
required
object

App to which the route destination directs traffic. Must provide either app or service instance.

object

Service instance to which the route destination directs traffic. Must provide either app or service instance.

weight
integer

Weight of the destination. Routes will equally distribute the traffic to all destinations with the same weight.

port
integer

Port of the destination that receives traffic.

protocol
string
Enum: "http1" "http2"

Protocol of the destination that receives traffic. Defaults to 'http1' when not specified for HTTP routes, and is ignored for TCP routes.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "destinations": [
    ]
}

Update a destination protocol for a route

Update the protocol of a specific route destination by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

destination_guid
required
string <uuid>

The GUID of the route destination

Request Body schema: application/json
required

Protocol of the destination

protocol
required
string
Enum: "http1" "http2"

Protocol of the destination

Responses

Request samples

Content type
application/json
{
  • "protocol": "http1"
}

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "app": {
    },
  • "weight": 0,
  • "port": 0,
  • "protocol": "http1",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "links": { }
}

Remove destination for a route

Remove a destination from a specific route by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

destination_guid
required
string <uuid>

The GUID of the route destination to remove

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Delete unmapped routes for a space

Delete routes that are unmapped in a specific space.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

SecurityGroups

SecurityGroups define the network access rules for apps in the Cloud Foundry environment. They include rules for inbound and outbound traffic. SecurityGroups can be managed through endpoints that allow for creation, updating, deletion, and retrieval of security group details.

ServiceBrokers

ServiceBrokers provide a way to manage and provision services in the Cloud Foundry environment. They include information such as service plans, instances, and bindings. ServiceBrokers can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service broker details.

ServiceOfferings

ServiceOfferings represent the available services in the Cloud Foundry environment. They include information such as service plans, instances, and bindings. ServiceOfferings can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service offering details.

ServicePlans

ServicePlans define the configurations and pricing for services in the Cloud Foundry environment. They include information such as memory, instances, and routes. ServicePlans can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service plan details.

ServicePlanVisibility

ServicePlanVisibility defines the visibility and access rules for service plans in the Cloud Foundry environment. They include information such as organization and space access. ServicePlanVisibility can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service plan visibility details.

ServiceInstances

ServiceInstances represent the instances of services in the Cloud Foundry environment. They include information such as service plans, bindings, and credentials. ServiceInstances can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service instance details.

ServiceCredentialBinding

ServiceCredentialBinding provides a way to bind service instances to apps in the Cloud Foundry environment. They include information such as credentials and bindings. ServiceCredentialBinding can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service credential binding details.

ServiceRouteBinding

ServiceRouteBinding provides a way to bind service instances to routes in the Cloud Foundry environment. They include information such as credentials and bindings. ServiceRouteBinding can be managed through endpoints that allow for creation, updating, deletion, and retrieval of service route binding details.

ServiceUsageEvents

ServiceUsageEvents track the usage and activity of services in the Cloud Foundry environment. They provide insights into service lifecycle changes, such as creation, deletion, and updates. ServiceUsageEvents are useful for monitoring and auditing purposes, helping administrators understand how services are being used and identify any issues. They can be retrieved through endpoints that provide detailed information about each event.

Sidecars

Sidecars represent additional processes that run alongside the main app processes in the Cloud Foundry environment. They provide additional functionality, such as logging, monitoring, and security. Sidecars can be managed through endpoints that allow for creation, updating, deletion, and retrieval of sidecar details.

Spaces

Spaces represent the logical grouping of resources within an organization in the Cloud Foundry environment. They provide a way to manage apps, services, and users within a specific context. Spaces can be managed through endpoints that allow for creation, updating, deletion, and retrieval of space details.

SpaceFeatures

SpaceFeatures provide additional capabilities and configurations for spaces in the Cloud Foundry environment. These features can include things like auto-scaling, health checks, and custom domains. SpaceFeatures enhance the functionality of spaces by allowing administrators to enable or disable specific features based on their requirements. They can be managed through endpoints that allow for enabling, disabling, and retrieving the status of space features.

SpaceQuotas

SpaceQuotas define the resource limits and constraints for spaces in the Cloud Foundry environment. They include limits on memory, instances, routes, and services. SpaceQuotas can be managed through endpoints that allow for creation, updating, deletion, and retrieval of space quota details.

Stacks

Stacks are the base operating system and file system that your application will execute in. A stack is how you configure applications to run against different operating systems (like Windows or Linux) and different versions of those operating systems (like Windows 2012 or Windows 2016).

An application’s lifecycle will specify which stack to execute the application in. Buildpacks can also be associated with a particular stack if they contain stack-specific logic. An application will automatically use buildpacks associated with the application’s configured stack.

Stacks are not used for apps with a Docker lifecycle.

Tasks

Tasks represent one-off processes that can be run in the Cloud Foundry environment. They provide a way to execute background jobs, data migrations, and other tasks that are not part of the main app processes. Tasks can be managed through endpoints that allow for creation, updating, deletion, and retrieval of task details.

Users

Users represent the individuals who have access to the Cloud Foundry environment. They include information such as roles, permissions, and credentials. Users can be managed through endpoints that allow for creation, updating, deletion, and retrieval of user details.

List users

Retrieve all users the user has access to.

query Parameters
page
integer

Page to display; valid values are integers >= 1

perPage
integer

Number of results per page, valid values are 1 through 5000

order_by
string

Order results by a specific field. Prepend with - to sort descending.

created_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

updated_ats
string

Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.

guids
Array of strings

Comma-delimited list of user guids to filter by

usernames
Array of strings

Comma-delimited list of usernames to filter by

origins
Array of strings

Comma-delimited list of user origins to filter by

Responses

Response samples

Content type
application/json
{
  • "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "pagination": {
    },
  • "resources": [
    ]
}

Create a user

Create a new user.

Request Body schema: application/json

User to create

guid
required
string

Unique identifier for the user

created_at
string <date-time>

The time with zone when the object was created

updated_at
string <date-time>

The time with zone when the object was last updated

username
string

The username of the user

presentation_name
string

The presentation name of the user

origin
string

The origin of the user

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

links
object (links)

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

Responses

Request samples

Content type
application/json
{
  • "guid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": { }
}

Response samples

Content type
application/json
{
  • "guid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": { }
}

Get a user

Retrieve a user by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "guid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": { }
}

Update a user

Update an existing user.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Request Body schema: application/json

User to update

username
string

The username of the user

presentation_name
string

The presentation name of the user

origin
string

The origin of the user

object (metadata)

Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource.

links
object (links)

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

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": { }
}

Response samples

Content type
application/json
{
  • "guid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "presentation_name": "string",
  • "origin": "string",
  • "metadata": {
    },
  • "links": { }
}

Delete a user

Delete a user by its GUID.

Authorizations:
oauth
path Parameters
guid
required
string <uuid>

The GUID of the resource

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}