Manifests API

The Manifests API provides endpoints for managing team manifests -- declarative configurations that define composable AI teams with versioned components.

What the Manifests API Does

Team manifests follow the "npm for AI agents" paradigm. The API allows you to validate manifest syntax, resolve component versions (dry run), deploy teams from manifests, upgrade components, rollback to previous versions, and export current team state.

Component References

Components use URI-based references:

Type	Pattern	Example
Store	store://type/name@version	store://agents/sdr-agent@^1.0.0
Local	local://type/name	local://agents/my-custom-agent
External	external://provider/id	external://heygen/avatar-emma

Version Specifiers

Specifier	Example	Matches
Exact	1.2.3	Only 1.2.3
Caret	^1.0.0	1.x.x (minor/patch)
Tilde	~1.2.0	1.2.x (patch only)

Deployment Features

• Model alias resolution -- aliases like claude-sonnet-latest are resolved to concrete model IDs at deploy-time
• Authorization grants -- OpenFGA tuples provisioned from manifest declarations (non-fatal if unavailable)
• SPIFFE identity -- agents receive SPIFFE IDs automatically with optional SVID configuration
• Catalog validation -- YAML manifests validated against Zod schemas on load (warn-only)

Error Codes

Code	Description
INVALID_MANIFEST	Manifest syntax is invalid
COMPONENT_NOT_FOUND	Referenced component doesn't exist
VERSION_NOT_SATISFIABLE	No version matches constraint
DEPLOYMENT_EXISTS	Team already deployed (use force)
RESOLUTION_FAILED	Could not resolve all components
ROLLBACK_FAILED	Target version not available
LOCKED_COMPONENT	Cannot upgrade locked component

Endpoints

Method	Endpoint	Description
POST	/manifests/validate	Validate manifest syntax
POST	/manifests/resolve	Resolve versions (dry run)
POST	/manifests/deploy	Deploy team from manifest
GET	/manifests	List all deployments
GET	/manifests/:deployId	Get deployment details
GET	/manifests/:deployId/export	Export as manifest
POST	/manifests/:deployId/upgrade	Upgrade components
POST	/manifests/:deployId/rollback	Rollback component
GET	/manifests/deployments	List deployments
GET	/manifests/deployments/:teamSlug	Get deployment by slug
GET	/manifests/deployments/:teamSlug/manifest	Export manifest by slug
GET	/manifests/deployments/:teamSlug/lockfile	Export lock file
POST	/manifests/deployments/:teamSlug/upgrade	Upgrade by slug
POST	/manifests/components/:type/:id/rollback	Rollback by component type

Validation

Send a manifest to /manifests/validate to check syntax before deploying. Returns validation errors and warnings without making any changes.

Resolution (Dry Run)

Send a manifest to /manifests/resolve to see what the lock file would look like with all versions resolved. No deployment occurs.

Deployment

Send a manifest to /manifests/deploy to create a complete team.

Deploy Options:

Option	Type	Default	Description
dryRun	boolean	false	Simulate deployment without changes
force	boolean	false	Override existing deployment
skipResolution	boolean	false	Skip version resolution
notes	string	--	Deployment notes for audit

The response includes the deployment ID, created agents, skills, and avatars.

Upgrade

Upgrade specific components or all components to newer versions. Supports dry-run mode to preview changes.

Upgrade Options:

Option	Type	Description
componentIds	string[]	Specific components to upgrade (all if omitted)
targetVersion	string	Target version constraint
allowBreaking	boolean	Allow major version upgrades
dryRun	boolean	Preview only

Rollback

Rollback a component to a previous version by specifying the component ID and target version number.

Export

Export the current deployment state as a portable manifest file, or export just the lock file with resolved versions.

Webhooks

Subscribe to manifest events: manifest.deployed, manifest.upgraded, manifest.rollback, component.update_available.

Catalog Validation Schemas

Schema	Validates
CatalogManifestSchema	Full manifest structure
CatalogAgentSchema	Agent definitions
CatalogOrchestrationSchema	Orchestration config
CatalogInteractionRuleSchema	Interaction rules
AuthorizationGrantSchema	Authorization grants
AgentIdentitySchema	SPIFFE identity config

See Also

• Team Manifests Guide - Manifest format reference
• Avatar Providers - External avatar config
• Store Overview - Browse and install components
• Agent Authorization - OpenFGA authorization details
• Agent Identity - SPIFFE identity system