API Bundles

Bundles are the public authoring artifacts in Centiceps. A bundle is either an API Bundle rooted at api.yaml or a Shared Flow Bundle rooted at shared-flow.yaml.

Known workspace structure

bundle/
├── api.yaml | shared-flow.yaml
├── routes/                 # API Bundles only
├── targets/                # API Bundles only
├── policies/
└── resources/

Unknown top-level files and folders are invalid. Paths must be relative, normalized, and free of .. segments or symbolic links.

Canonical child names

Child paths derive from the stable name inside the document:

Document	Required path
Route named orders	routes/orders.yaml
Target named default	targets/default.yaml
Policy named verify-token	policies/verify-token.policy.yaml

The control plane rejects mismatches instead of silently creating two identities.

Route order

An API root declares routeOrder. Only listed routes are part of the active execution graph and their order defines match precedence. Unlisted route files remain valid drafts in the saved workspace.

routeOrder:
  - order-by-id
  - orders
  - catch-all

Save, publish, and deploy

• Save preserves the complete workspace, including disconnected drafts.
• Publish freezes the workspace into an immutable revision.
• Deploy compiles the reachable graph and points an environment at that revision.
• Rollback is a new deployment that selects a previous revision.

Reachability

The deployment compiler starts at active root flows and routeOrder, then follows referenced targets, policies, Shared Flows, and resources. Disconnected files remain in the revision but do not enter the runtime snapshot.

This keeps authoring flexible without shipping unused scripts or policies into gateway memory.