<!-- Markdown twin of https://pixelvault.dev/docs/api/projects/ -->

[API reference](/docs/api/)

# Projects

Isolate media, API keys, usage, webhooks and idempotency keys inside one account. Free includes 1 project, Starter 3 and Pro 10.

-   GET [List account projects](#list_projects)
-   POST [Create a project](#create_project)
-   PATCH [Rename a project](#update_project)
-   DELETE [Delete an empty project](#delete_project)

## List account projects

GET `/v1/projects`

Lists every project owned by the account and the plan's project limit. Secret API keys mark their own project as `current`; dashboard sessions return the same account-level list.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Responses

-   200
    
    Projects and plan limit
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`project_management_forbidden`](/docs/errors/#project_management_forbidden): publishable keys cannot manage projects. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    

Request

curlNode.jsPython

```
curl https://api.pixelvault.dev/v1/projects \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": [
    {
      "id": "proj_abc123",
      "name": "Production",
      "created_at": "2026-11-17T09:30:00Z",
      "current": true
    }
  ],
  "meta": {
    "limit": 3,
    "total": 2
  }
}
```

## Create a project

POST `/v1/projects`

Creates an isolated project and its first live secret key. The raw `api_key` is returned once. A full plan returns 409 [`project_limit_reached`](/docs/errors/#project_limit_reached).

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`name`

string

Required

min length 1 · max length 100

### Responses

-   201
    
    Project and initial key created
    
-   400
    
    [`invalid_json`](/docs/errors/#invalid_json) or [`validation_error`](/docs/errors/#validation_error): name is missing, empty or longer than 100 characters.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`project_management_forbidden`](/docs/errors/#project_management_forbidden): publishable keys cannot manage projects. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   409
    
    [`project_limit_reached`](/docs/errors/#project_limit_reached): the account already has the maximum projects for its plan.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/projects \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}'
```

Response 201

```
{
  "data": {
    "project": {
      "id": "proj_abc123",
      "name": "Production",
      "created_at": "2026-11-17T09:30:00Z"
    },
    "api_key": "pv_live_…",
    "key_id": "key_abc123"
  }
}
```

## Rename a project

PATCH `/v1/projects/{id}`

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Project id (`proj_` prefix).

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`name`

string

Required

min length 1 · max length 100

### Responses

-   200
    
    Renamed project
    
-   400
    
    [`invalid_json`](/docs/errors/#invalid_json) or [`validation_error`](/docs/errors/#validation_error): name is missing, empty or longer than 100 characters.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`project_management_forbidden`](/docs/errors/#project_management_forbidden): publishable keys cannot manage projects. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`project_not_found`](/docs/errors/#project_not_found): no project with this id belongs to the account.
    

Request

curlNode.jsPython

```
curl -X PATCH https://api.pixelvault.dev/v1/projects/id \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}'
```

Response 200

Renamed project

## Delete an empty project

DELETE `/v1/projects/{id}`

Deletes an empty non-final project and revokes its keys and webhooks. Remove media and custom domains first, then wait for multipart uploads or exports to finish. A secret API key cannot delete its own project.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Project id (`proj_` prefix).

### Responses

-   200
    
    Deleted project
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`project_management_forbidden`](/docs/errors/#project_management_forbidden): publishable keys cannot manage projects. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`project_not_found`](/docs/errors/#project_not_found): no project with this id belongs to the account.
    
-   409
    
    [`last_project`](/docs/errors/#last_project), [`cannot_delete_current_project`](/docs/errors/#cannot_delete_current_project), `project_has_custom_domains` or [`project_not_empty`](/docs/errors/#project_not_empty): choose another project or remove its custom domains, media and active jobs first.
    

Request

curlNode.jsPython

```
curl -X DELETE https://api.pixelvault.dev/v1/projects/id \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

Deleted project
