Scopix

Documentation

Projects API Reference

Project workspaces let you partition files and folders into isolated containers within your organization

Project Workspaces

Every organization has a Default project that is created automatically on registration. Files and folders that are not assigned to a specific project land in the Default project. The Default project cannot be renamed or deleted.

Key rules

  • • Maximum 50 projects per organization
  • • Project names must be unique within an organization (case-insensitive)
  • • Names: 1–255 characters, no path separators (/, \, \0)
  • • A project must be empty (no files or folders) before it can be deleted
  • • project_type controls which AI analysis presets apply: general or real_estate

Create a Project

POST/api/v2/projects

Create a new project workspace. Returns 201 Created.

Request

json
{
  "name": "Site Inspections 2025",   // required, 1-255 chars
  "description": "Photos from Q1 site visits",  // optional, max 2000
  "icon": "folder",                  // optional, max 50 chars (identifier string)
  "color": "#4A90E2",                // optional, hex color, max 7 chars
  "project_type": "general"          // optional, "general" | "real_estate", default: "general"
}

Response

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Site Inspections 2025",
  "description": "Photos from Q1 site visits",
  "icon": "folder",
  "color": "#4A90E2",
  "project_type": "general",
  "is_default": false,
  "folder_count": 0,
  "file_count": 0,
  "created_by": "660f9500-f39c-52e5-b827-557766550111",
  "created_at": "2025-03-01T09:00:00Z",
  "updated_at": "2025-03-01T09:00:00Z"
}


// Error responses:
// 409 PROJECT_NAME_EXISTS  — a project with this name already exists
// 409 PROJECT_LIMIT_REACHED — 50-project maximum reached

List Projects

GET/api/v2/projects

List all project workspaces for the organization. The Default project is always returned first.

Request

json
// Query parameters:
?limit=50   // optional, 1-100, default 50
&offset=0   // optional, default 0

Response

json
{
  "items": [
    {
      "id": "aa000000-0000-0000-0000-000000000001",
      "name": "Default",
      "description": "",
      "icon": null,
      "color": null,
      "project_type": "general",
      "is_default": true,
      "folder_count": 12,
      "file_count": 84,
      "created_by": null,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Site Inspections 2025",
      "description": "Photos from Q1 site visits",
      "icon": "folder",
      "color": "#4A90E2",
      "project_type": "general",
      "is_default": false,
      "folder_count": 3,
      "file_count": 22,
      "created_by": "660f9500-f39c-52e5-b827-557766550111",
      "created_at": "2025-03-01T09:00:00Z",
      "updated_at": "2025-03-01T09:00:00Z"
    }
  ],
  "total_count": 2,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

Get a Project

GET/api/v2/projects/{project_id}

Get a single project by ID. Includes up-to-date folder and file counts.

Response

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Site Inspections 2025",
  "description": "Photos from Q1 site visits",
  "icon": "folder",
  "color": "#4A90E2",
  "project_type": "general",
  "is_default": false,
  "folder_count": 3,
  "file_count": 22,
  "created_by": "660f9500-f39c-52e5-b827-557766550111",
  "created_at": "2025-03-01T09:00:00Z",
  "updated_at": "2025-03-01T09:15:00Z"
}


// 404 PROJECT_NOT_FOUND if the ID doesn't belong to your organization

Update a Project

PATCH/api/v2/projects/{project_id}

Partially update a project. All fields are optional — only include what you want to change.

Request

json
{
  "name": "Site Inspections Q1",     // optional, omit to keep current
  "description": "Updated description",
  "icon": "camera",
  "color": "#E24A90",
  "project_type": "real_estate"
}


// Constraints:
// - Cannot rename the Default project (422 BUSINESS_RULE_VIOLATION)
// - name must be unique within the organization (409 PROJECT_NAME_EXISTS)

Response

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Site Inspections Q1",
  "description": "Updated description",
  "icon": "camera",
  "color": "#E24A90",
  "project_type": "real_estate",
  "is_default": false,
  "folder_count": 3,
  "file_count": 22,
  "created_by": "660f9500-f39c-52e5-b827-557766550111",
  "created_at": "2025-03-01T09:00:00Z",
  "updated_at": "2025-03-01T09:30:00Z"
}

Delete a Project

DELETE/api/v2/projects/{project_id}

Delete an empty project. Returns 204 No Content on success.

Response

json
// 204 No Content — project deleted


// Error responses:
// 404 PROJECT_NOT_FOUND
// 409 PROJECT_NOT_EMPTY — project still contains folders or files; move or delete them first
// 422 BUSINESS_RULE_VIOLATION — cannot delete the Default project

Project must be empty

Move or delete all folders and files inside the project before attempting deletion. Use GET /api/v2/projects/{project_id} to check folder_count and file_count before deleting.

Project Types

general (default)

General-purpose workspace. Standard AI analysis presets apply. Suitable for most use cases including document processing, mixed media, and custom pipelines.

real_estate

Optimized for property photography and real estate workflows. Enables room-type classification, space analysis presets, and listing-aware AI features.

Error Codes

CodeHTTPDescription
PROJECT_NOT_FOUND404No project with that ID exists in your organization
PROJECT_NAME_EXISTS409A project with that name already exists (names are unique per organization)
PROJECT_LIMIT_REACHED409Organization has reached the 50-project maximum
PROJECT_NOT_EMPTY409Cannot delete a project that still contains folders or files
BUSINESS_RULE_VIOLATION422Attempted to rename or delete the Default project

Related

Folders Reference

Create folders scoped to a project with project_id

Files Reference

Filter and upload files within a specific project