canonical: https://jentic.com/apis/cfengine.com/cfengine

# CFEngine Enterprise API

Jentic publishes the only available OpenAPI specification for CFEngine Enterprise API, keeping it validated and agent-ready. The CFEngine Enterprise API is the REST surface of the CFEngine Mission Portal, used to drive infrastructure automation across managed hosts. It exposes endpoints for host inventory and class membership, role-based user management, ad hoc SQL queries against the hub database, and read access to settings and server status.

## For AI agents

Manage CFEngine Mission Portal hosts, RBAC users and roles, settings, and inventory queries against the CFEngine hub.

## Scope

Does not push or compile policy bundles, run remote agent commands, or stream raw agent logs - use for Mission Portal hub administration and inventory queries only.

## Capabilities

- List managed hosts and inspect per-host state, classes, and last-seen times against the CFEngine hub
- Create, update, lock, and delete Mission Portal user accounts
- Define and assign RBAC roles that scope which hosts and reports a user can access
- Group and filter hosts by hard classes to target policy bundles at specific subsets
- Restore previously deleted hosts back into the active inventory
- Read server status and update Mission Portal settings programmatically
- Run inventory SQL queries against the hub for custom reporting

## Use cases

### Managed Host Inventory

Pull a continuously updated inventory of every host running CFEngine across the estate, including each host's classes, last reported time, and identity. The `/api/host` and `/api/hosts/by-class` endpoints power custom dashboards, drift detection, and audit reports without scraping the Mission Portal UI. Useful for compliance teams who need an authoritative list of which hosts are still under configuration management.

Example prompt: Call GET `/api/host` and GET `/api/hosts/by-class` then return every host id whose classes include 'cfengine_3'

### RBAC User Provisioning

Provision and deprovision Mission Portal user accounts and the roles that scope their access. PUT `/api/user/{username}` creates an account, POST `/api/user/{username}` updates it, and the matching `/api/role` endpoints define which hosts and reports each role can see. Used by platform teams that want IdP-driven onboarding rather than manual Mission Portal clicks.

Example prompt: Call PUT `/api/user/jane.doe` with a payload containing email, password and role 'cf_remoteuser', then verify with GET `/api/user/jane.doe`

### Host Lifecycle Management

Remove decommissioned hosts cleanly and recover from accidental deletions. DELETE `/api/host/{hostId}` drops a host from the hub, GET `/api/hosts/deleted` lists soft-deleted hosts still recoverable, and POST `/api/hosts/restore-deleted/{hostId}` brings one back. This avoids the common pitfall of orphaned host records skewing inventory counts after fleet churn.

Example prompt: Call GET `/api/hosts/deleted`, then for each host id call POST `/api/hosts/restore-deleted/{hostId}` until the active inventory matches the expected count

### AI Agent Infrastructure Audit via Jentic

An ops agent receives a request such as 'tell me which hosts are missing the latest policy class' and needs to call the CFEngine hub directly. Through Jentic, the agent searches for the right operation, loads the input schema, and calls `/api/hosts/by-class` with credentials drawn from your Jentic One instance. The agent returns a typed list of host ids without the developer wiring HTTP basic auth or paging logic.

Example prompt: Use Jentic to search 'list cfengine hosts by class', load the operation, and execute it for class 'compliance_baseline_v2'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/host` | List all managed hosts |
| GET | `/api/host/{hostId}` | Get details for a single host |
| GET | `/api/hosts/by-class` | Group hosts by hard classes |
| DELETE | `/api/host/{hostId}` | Remove a host from the hub |
| POST | `/api/hosts/restore-deleted/{hostId}` | Restore a deleted host |
| PUT | `/api/user/{username}` | Create a new Mission Portal user |
| GET | `/api/role` | List RBAC roles |
| GET | `/api/settings` | Read Mission Portal settings |

## Key resources

- **Hosts** — List, inspect, group by class, delete, and restore CFEngine-managed hosts
- **Users** — Create, read, update, delete, and unlock Mission Portal user accounts
- **Roles** — Define RBAC roles that scope user access to hosts and reports
- **Settings** — Read and update Mission Portal configuration settings
- **Server Status** — Read overall hub health and reachability

## Why Jentic

- **Setup:** Wiring the CFEngine Enterprise API by hand means handling HTTP basic auth against the Mission Portal hub and mapping intents onto its host, user, role, and settings endpoints yourself. Through Jentic you install once, import the CFEngine Enterprise API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** CFEngine puts the host id in the URL path for operations like `/api/host/{hostId}`, so a rule can pin your agent to reads for one host. You choose the operations it may call, so writes like deleting a host or updating a user are not included unless you add them.
- **Credential handling:** Your CFEngine basic-auth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list cfengine hosts' or 'get a host's inventory', and Jentic returns the matching CFEngine operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Puppet API** — Configuration management platform with a similar host inventory and node classification model
- **HashiCorp Nomad API** — Workload orchestrator for containers, batch, and system jobs across the same fleet
- **HashiCorp Nomad (vendor surface)** — Vendor-published Nomad API surface for orchestration alongside CFEngine-managed hosts

## FAQ

### Why is there no official OpenAPI spec for CFEngine Enterprise API?

CFEngine does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call CFEngine Enterprise 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 CFEngine Enterprise API use?

The API uses HTTP Basic authentication with Mission Portal credentials. Through Jentic, the username and password live in your Jentic One instance and are added to the Authorization header at execution time so they never enter the agent's prompt or context window.

### Can I list every host managed by CFEngine through the API?

Yes. GET `/api/host` returns the full inventory of hosts known to the hub, and GET `/api/hosts/by-class` groups the same hosts by their hard classes for targeted policy work. Each host record includes its id and last-seen timestamp.

### What are the rate limits for the CFEngine Enterprise API?

CFEngine does not publish a fixed cloud rate limit because the API runs on a self-hosted Mission Portal. Throughput is bounded by the hub's hardware and by basic-auth login throttling configured locally; treat large inventory pulls as you would any internal database query.

### How do I create a new Mission Portal user with the CFEngine API through Jentic?

Search Jentic for 'create a cfengine user', load the operation backed by PUT `/api/user/{username}`, and execute it with the username, email, password, and role payload. Jentic injects the basic-auth credentials so the agent only handles the typed input.

### Can I restore a host that was accidentally deleted from the CFEngine hub?

Yes. Soft-deleted hosts remain recoverable until the configured retention window passes. List them with GET `/api/hosts/deleted`, then call POST `/api/hosts/restore-deleted/{hostId}` for each id to bring them back into active inventory.

### Can I limit what my agent is allowed to do with the CFEngine Enterprise API?

Yes. Because you self-host Jentic One, your own rules decide which CFEngine operations and credentials the agent may use. You choose the operations it can call, so writes such as DELETE `/api/host/{hostId}` or updates to a Mission Portal user are excluded unless you add them, leaving the agent with reads like GET `/api/host` and GET `/api/hosts/by-class.` Since CFEngine puts the host id in the URL path, a rule can even pin the agent to a single host.