canonical: https://jentic.com/apis/prefect.io/prefect

# Prefect Cloud API

The Prefect Cloud API manages workflow orchestration platform resources including accounts, workspaces, teams, memberships, service account bots, invitations, and workspace-level access control. It provides 52 endpoints for administering the Prefect Cloud environment where data pipelines and workflow deployments run, with bearer token authentication and organization-scoped resource management.

## For AI agents

Manage Prefect Cloud accounts, workspaces, teams, service account bots, and access control for workflow orchestration environments.

## Scope

Does not handle flow definitions, task execution, or pipeline scheduling -- use for Prefect Cloud platform administration only.

## Capabilities

- Retrieve current actor profile and associated accounts and workspaces
- Manage account settings including billing and organizational preferences
- Create and configure teams with membership and workspace role assignments
- Provision service account bots for automated pipeline authentication
- Invite users to accounts with configurable workspace access roles
- Control workspace-level permissions through role-based access scoping
- Manage API keys and sessions for programmatic platform access

## Use cases

### Service Account Provisioning for Pipelines

Create and manage service account bots that authenticate automated data pipelines against Prefect Cloud. Bots receive scoped API keys that allow pipeline agents to register flow runs, report status, and interact with the orchestration platform without using personal credentials.

Example prompt: Create a new service account bot via POST /api/accounts/{account_id}/bots/ with a descriptive name, then retrieve its API key for use in pipeline configuration

### Team and Access Control Management

Organize Prefect Cloud users into teams and assign workspace-level roles that control what operations each team can perform. The API supports creating teams, managing memberships, and configuring workspace access roles to enforce least-privilege access across data engineering organizations.

Example prompt: Create a team via POST /api/accounts/{account_id}/teams/ with name 'Data Engineering', then grant workspace access via POST /api/accounts/{account_id}/teams/{id}/workspace_access with the appropriate role

### Multi-Workspace Organization Setup

Set up and manage multiple workspaces within a Prefect Cloud account to isolate environments (development, staging, production) for data pipeline deployments. The API enables programmatic workspace discovery, settings management, and user provisioning across workspace boundaries.

Example prompt: List all workspaces via GET /api/me/workspaces, check scopes for a target workspace via GET /api/me/workspaces/{workspace_id}/scopes, and verify the current user has deployment permissions

### AI Agent Prefect Administration via Jentic

Enable AI agents to administer Prefect Cloud environments through Jentic by searching for platform management operations, loading schemas, and executing calls. Agents can provision service accounts, manage team access, and configure workspaces without handling bearer tokens directly.

Example prompt: Search Jentic for 'create service account bot in Prefect', load the Prefect bot creation schema, and execute POST /api/accounts/{account_id}/bots/ with the required configuration

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /api/me/ | Get current actor profile |
| GET | /api/me/workspaces | List actor's workspaces |
| GET | /api/accounts/{account_id} | Get account details |
| POST | /api/accounts/{account_id}/teams/ | Create a team |
| POST | /api/accounts/{account_id}/bots/ | Create a service account bot |
| POST | /api/accounts/{account_id}/invitations/ | Invite a user to the account |
| GET | /api/me/workspaces/{workspace_id}/scopes | List workspace permission scopes |
| GET | /api/me/api_keys | List actor's API keys |

## Key resources

- **Accounts** — Organization-level accounts with settings and billing
- **Workspaces** — Isolated environments for pipeline deployments
- **Teams** — User groups with configurable workspace access roles
- **Bots** — Service accounts for automated pipeline authentication
- **Invitations** — User invitations with workspace role assignments
- **Memberships** — Account and team membership management

## Why Jentic

- **Setup:** Wiring the Prefect Cloud API by hand means putting your API key in a bearer Authorization header against api.prefect.cloud and resolving account and workspace ids across calls yourself. Through Jentic you install once, import the Prefect Cloud API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Prefect Cloud puts the account and workspace ids in the URL path (/accounts/{account_id}/..., /me/workspaces/{workspace_id}/...), so a rule can pin your agent to one account: it can read that account's workspaces and scopes and nothing else. You choose the operations it may call, so creating teams, bots, or invitations is not included unless you add it.
- **Credential handling:** Your Prefect Cloud API key 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 'create a service account bot in Prefect' or 'list my workspaces', and Jentic returns the matching Prefect Cloud operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Temporal API** — Durable workflow execution engine with replay and retry capabilities
- **n8n API** — Visual workflow automation platform with no-code node-based design
- **Mixpanel API** — Product analytics platform that consumes data from orchestrated pipelines

## FAQ

### What authentication does the Prefect Cloud API use?

The Prefect Cloud API uses bearer token authentication. Pass your API key in the Authorization header as 'Bearer <api-key>'. API keys can be created from the Prefect Cloud UI or via the /api/me/api_keys endpoint. Through Jentic, these keys are stored encrypted and agents receive scoped access.

### Can I create service account bots with the Prefect Cloud API?

Yes. The POST /api/accounts/{account_id}/bots/ endpoint creates service account bots that receive their own API keys for automated pipeline authentication. Bots operate independently of user accounts and can be scoped to specific workspaces.

### What are the rate limits for the Prefect Cloud API?

Prefect Cloud applies rate limiting based on your account plan tier. Free tier accounts have lower limits than Pro and Enterprise tiers. The API returns HTTP 429 responses when limits are exceeded with a Retry-After header indicating when to retry.

### How do I manage workspace access through Jentic?

Install the Jentic SDK with pip install jentic, then search for 'manage Prefect workspace access'. Jentic returns operations for listing workspaces, checking scopes, and assigning workspace roles to teams. Execute the relevant operation to configure access control.

### Does the Prefect Cloud API cover flow run management?

This specification covers the platform administration API including accounts, workspaces, teams, bots, and access control. Flow run creation, scheduling, and monitoring are handled through the workspace-scoped Prefect Server API, which operates within individual workspace contexts.

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

Yes. Because you run Jentic One yourself, your own rules decide which Prefect Cloud operations and credentials the agent may use. Prefect Cloud puts the account and workspace ids in the URL path (/accounts/{account_id}/..., /me/workspaces/{workspace_id}/...), so you can pin the agent to a single account and let it only read that account's workspaces and scopes via GET /api/me/workspaces and GET /api/me/workspaces/{workspace_id}/scopes. Write actions such as creating teams (POST /api/accounts/{account_id}/teams/), service account bots, or invitations stay off unless you explicitly add them to the allowed set.