# Projects

Source: https://docs.arcweave.com/rest-api/projects
Section: REST API
Description: REST API endpoints for listing and managing workspace projects

These endpoints list, create, import, rename, and delete projects in the current workspace.

## Endpoints

Context: Arcweave docs > REST API > Projects > Endpoints

### List workspace projects

Context: Arcweave docs > REST API > Projects > Endpoints > List workspace projects

`GET /api/v1/workspace/projects`

The key needs **Read projects** (`project:read`), and its owner needs **View projects list** for the key's workspace. Without workspace **View projects list**, this endpoint returns `403 Forbidden`, including when the owner participates in individual projects as an external member.

**Request**

```http title="HTTP"
GET /api/v1/workspace/projects
```

```bash title="curl"
curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/workspace/projects"
```

**Response**

Returns `200 OK`.

The response lists every active project in the key's workspace, without pagination. Projects are ordered by their latest data update. Each entry contains the public project hash, name, timestamps, and status:

```json
[
  {
    "hash": "ra6XRNxl3G",
    "name": "The Castle",
    "updatedAt": "2026-07-12T10:15:30.000000Z",
    "createdAt": "2026-01-05T13:43:32.000000Z",
    "status": "active"
  }
]
```

### List user workspace projects

Context: Arcweave docs > REST API > Projects > Endpoints > List user workspace projects

`GET /api/v1/user/projects`

**Warning: Deprecated endpoint**
`GET /api/v1/user/projects` is an alias of `GET /api/v1/workspace/projects`. It is deprecated and will be removed soon. New integrations should use `GET /api/v1/workspace/projects`, and existing integrations should migrate to it.

**Request**

```http title="HTTP"
GET /api/v1/user/projects
```

```bash title="curl"
curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/user/projects"
```

**Response**

Returns `200 OK`.

Projects are ordered by their latest data update. The response has the same shape as the workspace projects endpoint:

```json
[
  {
    "hash": "ra6XRNxl3G",
    "name": "The Castle",
    "updatedAt": "2026-07-12T10:15:30.000000Z",
    "createdAt": "2026-01-05T13:43:32.000000Z",
    "status": "active"
  }
]
```

### Create project

Context: Arcweave docs > REST API > Projects > Endpoints > Create project

`POST /api/v1/workspace/projects`

**Request**

```http title="HTTP"
POST /api/v1/workspace/projects
```

```bash title="curl"
curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/workspace/projects"
```

```json
{
  "template": "empty"
}
```

Request fields:

| Property   | Required | Type   | Description                                  |
| ---------- | -------- | ------ | -------------------------------------------- |
| `template` | Yes      | String | Template used to initialize the new project. |

Supported templates:

| Value                      | Template                    |
| -------------------------- | --------------------------- |
| `empty`                    | Blank Project               |
| `sample`                   | Interactive Fiction Example |
| `video-sample`             | Interactive Movie Example   |
| `game-engine-sample`       | Game Engine Example         |
| `tabletop-campaign-sample` | Tabletop Campaign Example   |
| `visual-novel`             | Visual Novel Example        |
| `cyber-security-sample`    | Serious Games Example       |

The token owner must have permission to create projects, and the workspace must have capacity for another project. Unknown root fields are rejected.

The new project uses the template's default name, such as `Untitled project` for `empty`. To change it, [rename the project](https://docs.arcweave.com/rest-api/projects#rename-project).

**Response**

Returns `201 Created` with the new project's numeric ID and public hash:

```json
{
  "message": "Successful project creation",
  "projectId": 1234,
  "hash": "ra6XRNxl3G"
}
```

### Import project

Context: Arcweave docs > REST API > Projects > Endpoints > Import project

`POST /api/v1/workspace/projects/import`

**Info: Rate limits**
Project imports and exports share a workspace quota of **3 requests per minute per purchased seat**. Import requests also count toward the overall API quota of **60 requests per minute per purchased seat**. See [Rate limits](https://docs.arcweave.com/rest-api/overview#rate-limits) for seat allowances, shared quotas, and retry guidance.

**Request**

```http title="HTTP"
POST /api/v1/workspace/projects/import
```

```bash title="curl"
curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/workspace/projects/import"
```

```json
{
  "name": "Generated game",
  "project": {
    "startingElement": "65139ea3-331f-4b25-88b4-ea7a65ff106c",
    "boards": {
      "e723bdc8-f5f3-4cbc-875d-f559ca40b511": {
        "name": "Generated Board",
        "elements": ["65139ea3-331f-4b25-88b4-ea7a65ff106c"],
        "notes": [],
        "jumpers": [],
        "branches": [],
        "connections": []
      }
    },
    "elements": {
      "65139ea3-331f-4b25-88b4-ea7a65ff106c": {
        "title": "Opening",
        "content": "<p>Hello world</p>",
        "outputs": []
      }
    }
  }
}
```

Request fields:

| Property  | Required | Type   | Description                                                                                   |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `name`    | Yes      | String | New project name, up to 255 characters. Used as supplied without an `Imported -` prefix.      |
| `project` | Yes      | Object | Project data to import. Accepts an Arcweave JSON export or collection maps as in the example. |

Import creates a new project in the key's workspace. It does not replace or merge into an existing project. The key needs `project:write`, and its owner needs permission to import projects. Workspace project and item limits still apply.

Collections can be maps keyed by resource UUIDs or objects containing a `byId` map. Use valid UUID v4 IDs and consistent references; the server validates project integrity and rich-text content. Missing collection roots and default fields are generated. Existing board variables in imported data are migrated to board attributes.

A [JSON export](https://docs.arcweave.com/rest-api/exports#json-export) can be supplied directly as `project`. This imports project content and structure; asset files are not restored. The asset collection is reset to an empty root, element/component asset references are removed, and asset-list attribute values are cleared. Upload and attach media separately using the [asset endpoints](https://docs.arcweave.com/rest-api/assets).

REST JSON exports also omit board-item positions and element/note dimensions and automatic-height settings. Importing one generates new positions and uses default dimensions, so the original layout is not preserved. To preserve layout, supply JSON exported from the editor with [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) enabled.

**Response**

Returns `201 Created` with the new project's identifiers and name:

```json
{
  "hash": "ra6XRNxl3G",
  "projectId": 1234,
  "name": "Generated game"
}
```

If the payload includes [`exportVersion`](https://docs.arcweave.com/integrations/json#project-level), it must be the number `1`. Omit it for data that isn't an Arcweave JSON export.

Invalid payloads, an unsupported `exportVersion`, inconsistent references, invalid rich text, invalid Arcscript, or exceeded project/item limits return `400 Bad Request`. Import integrity errors use the title `Project integrity exception during import.`; each entry in `errors` has a `type`, such as `ItemLimitExceeded`, and a `text` description. Invalid Arcscript uses the title `Bad Request - invalid Arcscript`.

### Rename project

Context: Arcweave docs > REST API > Projects > Endpoints > Rename project

`PATCH /api/v1/{hash}`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}
```

```bash title="curl"
curl --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH"
```

```json
{
  "name": "The Castle: Remastered"
}
```

Request fields:

| Property | Required | Type   | Description                                  |
| -------- | -------- | ------ | -------------------------------------------- |
| `name`   | Yes      | String | New project name. Maximum length: 255 chars. |

`name` must not be empty. Unknown root fields are rejected. The token owner must have permission to edit the project.

**Response**

Returns `200 OK`:

```json
{
  "message": "Project name was successfully updated"
}
```

### Delete project

Context: Arcweave docs > REST API > Projects > Endpoints > Delete project

`DELETE /api/v1/{hash}`

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}
```

```bash title="curl"
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH"
```

The token owner must have permission to delete the project.

**Response**

Returns `200 OK`:

```json
{
  "message": "Successful project deletion"
}
```

## Common errors

Context: Arcweave docs > REST API > Projects > Common errors

| Status | Meaning                                                               |
| ------ | --------------------------------------------------------------------- |
| `400`  | Invalid create, import, or rename payload, or import limit exceeded.  |
| `403`  | API access, project permission, or workspace project capacity denied. |
| `404`  | Project not found.                                                    |