canonical: https://jentic.com/apis/cloudfoundry.org/cloudfoundry

# Cloud Foundry V3 API

Jentic publishes the only available OpenAPI specification for Cloud Foundry V3 API, keeping it validated and agent-ready. Cloud Foundry V3 is the cloud controller API for the open-source platform-as-a-service used by SAP BTP, IBM, and other distributions. It introduces support for one-off tasks, multi-process applications via Procfiles, direct access to packages and droplets, and zero-downtime deployments that change source code without stopping the app. The spec covers 238 endpoints across apps, builds, deployments, droplets, organisations, spaces, service instances, and audit events.

## For AI agents

Manage Cloud Foundry applications, deployments, droplets, services, and organisations through the V3 cloud controller API using OAuth2 (UAA).

## Scope

Does not provision the underlying foundation, manage UAA users directly, or operate BOSH directors - use for application-layer Cloud Foundry operations only.

## Capabilities

- Push and start applications via `/v3/apps` and `/v3/apps/{guid}/actions/start`
- Trigger zero-downtime deployments to swap droplets without restart
- Run one-off tasks against an app for migrations or scheduled jobs
- List and manage organisations, spaces, and role assignments
- Bind service instances to apps and rotate credentials
- Stream audit events and app usage events for compliance reporting

## Use cases

### Continuous Deployment to Cloud Foundry

Drive zero-downtime application deployments from a CI pipeline. Upload a package, build a droplet, and POST a deployment to swap the running droplet on `/v3/apps/{guid}/relationships/current_droplet.` The deployment endpoint orchestrates rolling instance replacement so user traffic stays on the old droplet until the new one is healthy.

Example prompt: POST a package to `/v3/apps/{guid}/packages`, create a build, then PATCH `/v3/apps/{guid}/relationships/current_droplet` with the new droplet GUID.

### One-Off Task Execution

Run database migrations, data backfills, or scheduled jobs as one-off tasks attached to an application. Tasks share the app's droplet and environment, so the same code that serves traffic also executes the task. Useful for replacing standalone job runners with platform-native invocations.

Example prompt: POST `/v3/apps/{guid}/tasks` with command='rake db:migrate' and poll the task GUID until state=SUCCEEDED.

### Multi-Tenant Organisation Audit

Pull governance data across organisations and spaces for security and compliance reviews. Combine `/v3/organizations`, `/v3/spaces`, `/v3/users`, and `/v3/audit_events` to answer who did what, when, and against which app or service. Useful for SOC2 evidence collection on Cloud Foundry estates.

Example prompt: GET `/v3/audit_events` with created_ats[gte]=24h_ago and group results by organization_guid for the compliance report.

### AI Agent Cloud Foundry Operations

Let a Jentic-powered SRE agent operate a Cloud Foundry estate. The agent searches Jentic for 'restart a Cloud Foundry app' or 'list apps in a space', loads the matching V3 operation, and executes it. UAA OAuth2 credentials stay in your Jentic One instance.

Example prompt: Search Jentic for 'start a Cloud Foundry app', load the startApp operation, and execute POST `/v3/apps/{guid}/actions/start.`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v3/apps` | List applications |
| GET | `/v3/apps/{guid}` | Get a single application |
| POST | `/v3/apps/{guid}/actions/start` | Start an application |
| GET | `/v3/apps/{guid}/env` | Get application environment |
| PATCH | `/v3/apps/{guid}/relationships/current_droplet` | Swap the running droplet |
| GET | `/v3/apps/{guid}/droplets/current` | Get the current droplet for an app |
| GET | `/v3/apps/{guid}/permissions` | Get permissions for an app |
| GET | `/v3/apps/{guid}/ssh_enabled` | Check whether SSH is enabled |

## Key resources

- **Apps** — Application records, lifecycle, and environment at `/v3/apps.`
- **Builds** — Build artefacts produced from packages at `/v3/builds.`
- **Droplets** — Runnable artefacts that apps execute at `/v3/droplets.`
- **Deployments** — Zero-downtime deployment workflows at `/v3/deployments.`
- **Organizations and Spaces** — Tenant boundaries and role assignment at `/v3/organizations` and `/v3/spaces.`
- **Audit Events** — Platform-wide audit trail at `/v3/audit_events.`

## Why Jentic

- **Setup:** Wiring the Cloud Foundry V3 API by hand means running the UAA OAuth2 flow, refreshing scoped tokens, and resolving the per-landscape api.cf.{landscape}.hana.ondemand.com host across hundreds of endpoints yourself. Through Jentic you install once, import the Cloud Foundry V3 API from the API Directory, store the UAA credential once, and your agent calls it.
- **Permission scoping:** Cloud Foundry puts the app guid in the URL path (`/v3/apps/{guid}/...`), so a rule can pin your agent to one app: it can read that app's env, droplets, and permissions and nothing else. You choose the operations it may call, so lifecycle actions like starting the app or setting its current droplet are only in reach if you include them.
- **Credential handling:** Your Cloud Foundry UAA credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start a Cloud Foundry app' or 'read an app's environment', and Jentic returns the matching V3 operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Kubernetes API** — Container orchestrator that has largely replaced Cloud Foundry in new deployments.
- **Heroku Platform API** — Hosted PaaS with a similar app/build/release model.
- **GitHub API** — Source control and CI hooks that trigger Cloud Foundry deployments.

## FAQ

### Why is there no official OpenAPI spec for Cloud Foundry V3 API?

The Cloud Foundry community publishes reference docs but not a maintained OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Cloud Foundry V3 API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Cloud Foundry V3 API use?

The API uses OAuth2 against UAA (User Account and Authentication), the Cloud Foundry identity service. Obtain a token from your foundation's UAA endpoint and pass it as Authorization: Bearer <token>. Through Jentic, UAA tokens are stored encrypted in the vault.

### Can I do zero-downtime deployments through the V3 API?

Yes. PATCH `/v3/apps/{guid}/relationships/current_droplet` starts a rolling deployment that replaces instances in batches, keeping the old droplet serving traffic until the new one is healthy. The `/v3/deployments` resource exposes the in-flight state and lets you cancel.

### How do I run a one-off task on Cloud Foundry through Jentic?

Run jentic search 'run a one-off task on Cloud Foundry', load the createTask operation, and execute POST `/v3/apps/{guid}/tasks` with the command and disk and memory limits. Jentic handles the UAA bearer token from the stored credential.

### Does the API expose audit events?

Yes. GET `/v3/audit_events` returns platform-wide audit records, filterable by created_ats, target_guids, and types. This is the canonical source for compliance reporting on a Cloud Foundry estate.

### How do I list applications in a specific space?

GET `/v3/apps` with the space_guids query parameter set to the target space GUID. The response is paginated; follow the next link until no more pages remain. The same pattern works for filtering by organization_guids.

### Can I limit what my agent is allowed to do with the Cloud Foundry V3 API?

Yes. Because Jentic One is self-hosted, your own rules decide which Cloud Foundry operations and credentials the agent may use, and you pick exactly which V3 operations it can call. Since the app GUID sits in the URL path (`/v3/apps/{guid}/...`), you can pin the agent to a single app so it reads only that app's environment, droplets, and permissions and nothing else. Lifecycle actions such as starting the app via `/v3/apps/{guid}/actions/start` or swapping its current droplet are only in reach if you include those operations in the rule you set.