Projects - AIRCTRL

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

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.

​What you need

​Create a project

​API

​SDK

​CLI

​MCP

​List and read projects