Projects

A project groups an organization’s account kits and child projects (the tenant users you provision per end-user):

organization → project → (account_kit → child_project → primitives)

Use one when a single organization needs more than one scope — staging next to production, an acquired brand, one project per app you ship. If you don’t need that, you never see the layer: every organization has a default project and every call that names no project resolves to it.

Migration 059 created the default project for every existing organization and backfilled every account kit, child project, connection, vault entry and approval into it. Nothing written before projects existed changes behaviour — see Projects (architecture).

CLI first

naive projects list
naive projects create --name "Staging"
naive projects use <project_id>       # persisted; sent as X-Naive-Project-Id
naive projects use --clear            # back to the default project

naive use <child_project_id> --project <project_id>

Create a project

curl -X POST https://api.usenaive.ai/v1/projects \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Staging" }'

const project = await naive.projects.create({ name: "Staging" });

Response:

{
  "id": "b6c2b0f1-9a5d-4a03-9c66-1cb9c2b1d2f4",
  "organization_id": "3f8a4e21-0f1c-4d2b-9b0e-2f4b7c9a1d33",
  "company_id": "3f8a4e21-0f1c-4d2b-9b0e-2f4b7c9a1d33",
  "name": "Staging",
  "slug": "staging",
  "status": "active",
  "is_default": false,
  "created_at": "2026-08-02T18:31:04Z"
}

company_id is the deprecated spelling of the same id, returned so a caller written against the old name does not have to be rewritten.

Parameters

Param	Type	Required	Default	Description
`name`	string	Yes	—	Display name
`slug`	string	No	slugified `name`	URL-safe handle, unique in the organization
`settings`	object	No	—	Arbitrary JSON you can attach

Work inside a project

const project = naive.forProject(projectId);

const child = await project.childProjects.create({ external_id: "acme" });
await project.accountKits.list();

await project.forChild(child.id).cards.create({ spending_limit_cents: 25_000 });
await project.forChild(child.id).vault.list();

curl -X POST https://api.usenaive.ai/v1/projects/$PROJECT_ID/users \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "acme" }'

curl https://api.usenaive.ai/v1/users \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "X-Naive-Project-Id: $PROJECT_ID"

{ "name": "naive_vault_list", "arguments": { "user_id": "<child_project_id>", "project_id": "<project_id>" } }

forProject("default") declines to name a project rather than naming the default one: on an un-pinned key it resolves to the organization’s default project, and on a key pinned to another project it resolves to the pin. naive.forUser(id) is the same resolution without writing the sentinel.

Pin a key to a project

An API key can be pinned to a project at creation (active_project_id), the way it can be sealed to a subject. A pinned key can only act inside its project: a request naming a different one is a 403 key_project_mismatch, never a redirect. Leave the project off the path (or use default) to act inside the pin.

Delete a project

curl -X DELETE https://api.usenaive.ai/v1/projects/{project_id} \
  -H "Authorization: Bearer nv_sk_your_key"

Refused while the project still holds account kits or child projects — deleting it would cascade into every primitive underneath — and the default project can never be deleted.

Error handling

Error	Cause	Recovery
`not_found`	The `project_id` is not in your organization (or is malformed)	`GET /v1/projects` for the valid ids
`invalid_input`	Duplicate slug, deleting a non-empty project, deleting or archiving the default	Pick another slug, or empty the project first
`forbidden`	A sealed agent key tried to create a project, or a pinned key named another one	Use an organization key; projects are a governance write

Back-compat

Every old spelling keeps working and resolves to the default project: naive.forUser(id), naive.users, naive.accountKits, naive use <child_project_id>, /v1/users/..., /v1/company, and MCP tools called with user_id and no project_id.

Getting Started

Agent Profiles

Architecture

Primitives

CLI first

Create a project

Parameters

Work inside a project

Pin a key to a project

Delete a project

Error handling

Back-compat

​CLI first

​Create a project

​Parameters

​Work inside a project

​Pin a key to a project

​Delete a project

​Error handling

​Back-compat

CLI first

Create a project

Parameters

Work inside a project

Pin a key to a project

Delete a project

Error handling

Back-compat