Projects

A project groups records and gateways. Project access is independent: being a member of one project does not grant access to another.

What you need

A human PAT.
An account ID from GET /v1/accounts, listAccounts(), airctrl project accounts, or list_accounts.
The required permission for the action.

Action	Required permission
Create a project	`projects:create` in the account
Update a project	`projects:update` in that project
Archive or restore	`projects:archive` in that project

When you create a project, makes you its Project Administrator. This does not make you an administrator of projects created by other members.

Create a project

API

curl --request POST \
  --url "$AIRCTRL_API_URL/v1/projects" \
  --header "Authorization: Bearer $AIRCTRL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 00000000-0000-4000-8000-000000000020" \
  --data '{
    "accountId": "00000000-0000-4000-8000-000000000001",
    "name": "Payments service",
    "description": "Credentials used by the payments application"
  }'

{
  "ok": true,
  "data": {
    "project_id": "00000000-0000-4000-8000-000000000010"
  }
}

SDK

const project = await airctrl.createProject({
  accountId: '00000000-0000-4000-8000-000000000001',
  name: 'Payments service',
  description: 'Credentials used by the payments application',
})

console.log(project.project_id)

CLI

airctrl project create \
  --account 00000000-0000-4000-8000-000000000001 \
  --name "Payments service" \
  --description "Credentials used by the payments application"

MCP

Create an AIRCTRL project named "Payments service" in account
"00000000-0000-4000-8000-000000000001". Use "Credentials used by the
payments application" as its description. Show the final account, name and
description, then wait for my confirmation before creating it.

MCP tool used: create_project

List and read projects

SDK

const projects = await airctrl.listProjects({
  accountId: '00000000-0000-4000-8000-000000000001',
  includeArchived: false,
})

const project = await airctrl.getProject(
  '00000000-0000-4000-8000-000000000010',
  { accountId: '00000000-0000-4000-8000-000000000001' },
)

CLI

airctrl project list --account 00000000-0000-4000-8000-000000000001
airctrl project get 00000000-0000-4000-8000-000000000010 \
  --account 00000000-0000-4000-8000-000000000001

MCP

List the active projects in account "00000000-0000-4000-8000-000000000001".
Then show the safe details for project
"00000000-0000-4000-8000-000000000010". Do not change anything.

MCP tools used: list_projects, get_project

Update a project

Project updates replace all three editable fields. Send null to clear the description.

await airctrl.updateProject(
  '00000000-0000-4000-8000-000000000010',
  {
    name: 'Payments API',
    description: null,
    isActive: true,
  },
  { accountId: '00000000-0000-4000-8000-000000000001' },
)

CLI:

airctrl project update 00000000-0000-4000-8000-000000000010 \
  --account 00000000-0000-4000-8000-000000000001 \
  --name "Payments API" \
  --description null \
  --active true

MCP request:

Update project "00000000-0000-4000-8000-000000000010" in account
"00000000-0000-4000-8000-000000000001". Rename it to "Payments API", clear
its description and keep it active. Show every resulting value and wait for
my confirmation before changing it.

MCP tool used: update_project

Archive or restore

Archiving also makes the project inactive.

await airctrl.setProjectArchiveState(projectId, true, { accountId })
await airctrl.setProjectArchiveState(projectId, false, { accountId })

airctrl project archive "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID"
airctrl project restore "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID"

MCP request:

Archive project "00000000-0000-4000-8000-000000000010" in account
"00000000-0000-4000-8000-000000000001". Show its name, ID and current state,
then wait for my confirmation. Do not change any other project.

MCP tool used: set_project_archive

Groups and effective access

Groups are reusable within an account. Creating a group through a project does not grant it a role in that project. Assign a project role separately. Groups contain onboarded human account members, not Service Accounts or nested groups. Group collaboration requires Team or higher and the required RBAC permission. A plan does not grant a role, and a role does not override the plan. Revocation and cleanup remain permission-checked; they do not require unlocking the vault.

Action	Permission checked by the API
List groups or members	`groups:list`
Create, rename or delete a group	`groups:create`, `groups:update` or `groups:delete`, respectively
Add or remove a member	`groups:manage-members`; affected project roles are also checked
Grant a project role	`members:add`, `groups:manage-members` and authority to delegate that role
Revoke a project role	`members:remove` and `groups:manage-members`
Share or revoke one record with a group	`records:share-group` or `records:revoke-group`, respectively

Membership changes and group deletion also require the corresponding add/remove/share/revoke permissions on every affected project and direct record grant. The API checks the complete operation before committing it. Access is the union of authorized paths. Removing someone from one group does not remove access supplied by another group, direct project membership, ownership or a direct record share. Removing a project path can leave access to an individually shared record without leaving project access. Revoking a direct record share does not revoke project access.

Detail and Graph parity

Detail and Graph are two renderings of the same project. Detail opens the shared Notes manager from the right-rail Notes card; Graph opens it from the Notes node action. Both views invalidate the same project/query prefixes after writes. Graph expands the existing Members, Records, Notes, Audit, and Telemetry contracts; its Telemetry ranges are aggregated from that project’s gateway request logs instead of placeholder values. Archived or plan-locked projects remain readable while mutation controls stay unavailable. Record visibility and secret access are distinct permissions. A metadata-only role does not authorize decryption. The server evaluates each permission across the surviving paths; membership alone is not a permission. Adding a member later applies the group’s existing grants to that member. Removing a member or deleting a group removes only the corresponding paths. The server removes wrappers only where the corresponding effective access no longer exists and queues project re-keying when needed. Revocation cannot erase plaintext or keys someone already downloaded.

Complete pending encrypted access

Group membership and role writes persist authorization first. They return a snapshot with changed, wrapper-deletion counts and per-resource changes. A change can report material_pending.project_key, material_pending.record_key or rekey_queued. A successful write does not prove that the recipient can already decrypt every record. An authorized key holder completes the encrypted material locally with an unlocked vault. The Web app and SDK use the same reconciliation engine; CLI and MCP invoke that SDK. Reconciliation never grants permissions. If the holder cannot open the needed material, it can remain pending. Verify recipient access after reconciliation; attemptedProjectIds records attempts, not completed access. Use IDs returned by account/project discovery and the group catalog. Choose an existing delegable role; do not infer a role from a display name.

const catalog = await airctrl.getGroupCatalog(projectId, { accountId })
const role = catalog.roles.find(candidate => candidate.id === roleId)
if (!role) throw new Error('Choose a role from the group catalog')
const group = await airctrl.createGroup(projectId, { name: 'Payments team' }, { accountId })
await airctrl.addGroupMember(group.group_id, userId, { accountId })
const grant = await airctrl.grantProjectGroup(projectId, group.group_id, role.id, { accountId })
const reconciliation = await airctrl.reconcileGroupAccess({ accountId, projectIds: [projectId], vaultPassword })

With a human CLI login, reconcile after membership or grant changes using an authorized holder’s vault:

airctrl group add-member "$GROUP_ID" "$USER_ID" --account "$ACCOUNT_ID"
airctrl group reconcile --account "$ACCOUNT_ID" --project "$PROJECT_ID"

The optional project filter limits project reconciliation, not pending direct group-record shares in that account. Omitting it attempts readable projects in the selected account. Sharing one record with a group remains a separate operation; it does not grant access to its project. See SDK examples, CLI examples and MCP prompts.

Common failures

401: the PAT is missing, invalid or expired.
403: the caller lacks the required account or project permission.
409: a repeated write conflicts with the current state or idempotency key.
A project read can return null when the project is not available to the caller.

Getting Started

Guides

Reference

What you need

Create a project

API

SDK

CLI

MCP

List and read projects

SDK

CLI

MCP

Update a project

Archive or restore

Groups and effective access

Detail and Graph parity

Complete pending encrypted access

Common failures

​What you need

​Create a project

​API

​SDK

​CLI

​MCP

​List and read projects

​SDK

​CLI

​MCP

​Update a project

​Archive or restore

​Groups and effective access

​Detail and Graph parity

​Complete pending encrypted access

​Common failures

What you need

Create a project

API

SDK

CLI

MCP

List and read projects

SDK

CLI

MCP

Update a project

Archive or restore

Groups and effective access

Detail and Graph parity

Complete pending encrypted access

Common failures