Manage projects#

A project separates event data, identities, and delivery pipelines. Every analytics request targets one project ID. Credentials can hold access to several projects, and the server checks the target on every request.

Use the CLI, HTTP API, or a connected MCP agent. For the examples below, set PORCUPINE_URL and run porcupine login --admin with an instance administrator's email address.

List and create projects#

List the projects you can access:

porcupine list-projects

Create a project for backend-only capture:

porcupine create-project --body '{"name":"Demo","ingestion_mode":"server_only"}'

For browser capture, use "ingestion_mode":"mixed". The creation response includes the project's public ingest_token. Store it in your browser configuration and configure the application's allowed origin on the server. For private backend credentials, create a service key.

Keep the returned project ID for future requests. Creating a project requires management:write and events:write with instance-wide project scope. An instance administrator has that authority.

Rename a project#

Find the project ID with list-projects, then run:

porcupine rename-project --id PROJECT_ID --body '{"name":"Research"}'

Renaming requires management:write for the target project. It preserves the project ID, data, credentials, and pipelines.

Give someone access#

Invite a person with explicit permissions for each project. A person can have different permissions on several projects. An instance administrator can manage all projects.

For a backend or shared team agent, issue a service key scoped to its projects and required operations. Public ingestion keys cannot query events or administer the instance.

Delete a project#

Deletion permanently removes the project and its managed analytics and export objects. Check the project ID against list-projects before running this command. Only an instance administrator can delete a project.

porcupine delete-project --id PROJECT_ID

The server cancels pending project work and cleans up its managed data. Interrupted cleanup is retried after restart and periodically. A completed deletion returns HTTP 204, including on retry for the same ID. Backups and copies already sent to external destinations have separate retention policies. See project deletion and recovery.

Use an agent or HTTP#

Ask your MCP agent to list, create, rename, or delete the intended project. It discovers the relevant contract with porcupine_docs and executes it with porcupine_call. The operation IDs are list-projects, create-project, rename-project, and delete-project.

The HTTP routes are GET and POST /api/v1/projects, plus PATCH and DELETE /api/v1/projects/{id}. See the HTTP reference for the full permissions and response contract.