Project Registry API Guide

The Project Registry API is the system of record for projects: their metadata and settings, their manifest, the variables and secrets that workflows and agents receive, their bindings to other resources, and who has access. Most other integrations start here, because they need a project to anchor to. Swagger is the contract; this guide is the map.

Projects

Task	Call
Create a project (and optionally link a repository)	`POST /projects`
List the organization's projects	`GET /projects` (archived projects are excluded unless `includeArchived=true`)
Get or update	`GET` and `PATCH /projects/{projectId}`
Settings	`PATCH /projects/{projectId}/settings`, and `GET .../settings/typed` with defaults applied
Connections for a project	`PATCH /projects/{projectId}/connections/{type}` enables, disables or configures one
Preferred workspace image	`GET` and `PATCH /projects/{projectId}/preferred-image-variant`

Idempotent create. A create that carries a managedKey is a get-or-create per organization: 201 when it creates the project, 200 with the existing project unchanged when one exists, and 409 PROJECT_MANAGED_KEY_ARCHIVED when the match is archived. Only a workload may send a managedKey (403 PROJECT_MANAGED_KEY_WORKLOAD_REQUIRED otherwise), and a keyed create does not make the person a project member.

Archive or delete. Archiving retires a project reversibly: it leaves the default listing, accepts no more writes, and keeps all its data. unarchive is the exact inverse, and both are idempotent. DELETE is irreversible: it removes the project and everything attached to it and tells the rest of the platform to clean up. Before you delete, GET .../deletion-impact returns whether the delete is allowed, why not if it is blocked, and the counts of what would be destroyed. A project that a producer owns and would recreate cannot be deleted (409 PROJECT_MANAGED_DELETE_REFUSED). That is the hardDeletable flag on the project.

Bootstrap. POST .../bootstrap/analyze returns the bootstrap decision for the project's current state before anything runs, and POST .../bootstrap requests the bootstrap.

Variables and wallets

Variables live in wallets. A wallet has a lowercase kebab-case name, unique within its scope, and a description. The name cannot be changed later.

An org wallet (POST /wallets) is inherited by every project. A project wallet (POST /projects/{projectId}/wallets) belongs to one project. Listing a project's wallets returns both.
A variable has an uppercase key (^[A-Z][A-Z0-9_]*$, up to 256 characters), a value (up to 8192 characters), an optional description and an isSecret flag. Secret values are encrypted at rest and write-only: reading a wallet returns the variable keys and isSecret flags, never values.
Values are resolved only for running work. POST /projects/{projectId}/wallets/resolve (and POST /wallets/resolve for organization-level work) decrypts the named wallets under the authority of the member or delegated context that a workflow dispatch or a session start forwards. Project wallets are never returned from the organization-level resolve.

Manifest

The project manifest is a versioned description of the project's services, resources and connections. See Topology for what it shows.

Task	Call
Read the current manifest (`null` before one exists)	`GET /projects/{projectId}/manifest`
Replace it entirely	`PUT .../manifest`
Change part of it with a JSON merge patch	`PATCH .../manifest`
Check a manifest without saving	`POST .../manifest/validate`
History, one historical snapshot, a diff between two versions	`GET .../manifest/history`, `.../history/{version}`, `.../diff/{fromVersion}/{toVersion}`
Work on one section	`GET`, `PUT`, `PATCH` and `DELETE` on `.../manifest/services/{name}`, `.../resources/{name}` and `.../connections/{name}`, with a list call for each

Bindings

A binding attaches another resource to a project's references. POST /projects/{projectId}/bindings takes a kind, a targetId and an optional label. A KB_SPACE binding points at a knowledge-base space slug, which is checked against the Knowledge Base API. An EXTERNAL_PROJECT binding points at another project id in the same organization. List and delete bindings by project.

Access

Roles. POST .../roles/grant and .../roles/revoke give or take a project role. The role is admin or lead; any other value is refused with 400. GET .../roles lists assignments, and DELETE .../members/{userId} removes a user and their access record.
Shares. Resources can be shared with a subject at exactly one share level: GET, PUT and DELETE /resources/{type}/{id}/shares. Viewing shares needs view access; changing them needs manage access and the level involved.

Previous: ← Knowledge Base API Guide Next: Search and Rendering Guide →