> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Project

> Delete a specific project using its unique project ID. This action is permanent and cannot be undone.

## Overview

Permanently delete a project from your Pictory account using its unique identifier. This action removes the project and all associated data, including video files, audio, subtitles, and configuration settings.

<Warning>
  **This action is permanent and cannot be undone.** Once deleted, the project and all its associated files will be permanently removed from your account.
</Warning>

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
DELETE https://api.pictory.ai/pictoryapis/v2/projects/{projectid}
```

***

## Request Parameters

### Path Parameters

<ParamField path="projectid" type="string" required>
  The unique identifier of the project to delete. Can be either a string (for v3 schema projects) or an integer (for v2 schema and earlier projects).

  Example: `20251222191648030d7df02f5b4054d4ca8831f1369459e25`
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## Response

<ResponseField name="success" type="boolean">
  Indicates whether the deletion was successful
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message about the deletion
</ResponseField>

## Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true,
    "message": "Project deleted successfully"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "success": false,
    "message": "Project not found"
  }
  ```

  ```json 403 - Forbidden theme={null}
  {
    "success": false,
    "message": "You do not have permission to delete this project"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://api.pictory.ai/pictoryapis/v2/projects/YOUR_PROJECT_ID' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'accept: application/json' | python -m json.tool
  ```

  ```python Python theme={null}
  import requests

  project_id = "20251222191648030d7df02f5b4054d4ca8831f1369459e25"
  url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "accept": "application/json"
  }

  response = requests.delete(url, headers=headers)
  result = response.json()

  if result.get('success'):
      print(f"Project {project_id} deleted successfully")
  else:
      print(f"Failed to delete project: {result.get('message')}")
  ```

  ```javascript JavaScript theme={null}
  const projectId = '20251222191648030d7df02f5b4054d4ca8831f1369459e25';
  const response = await fetch(
    `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'accept': 'application/json'
      }
    }
  );

  const result = await response.json();

  if (result.success) {
    console.log(`Project ${projectId} deleted successfully`);
  } else {
    console.log(`Failed to delete project: ${result.message}`);
  }
  ```
</CodeGroup>

***

## Usage Notes

<Warning>
  **Permanent Deletion**: Deleted projects cannot be recovered. Ensure you have backups of any important project files (videos, audio, subtitles) before deleting.
</Warning>

<Tip>
  Before deleting a project, consider using the [Get Project By Id](/api-reference/projects/get-project-by-id) endpoint to retrieve and back up all project assets (video, audio, subtitle files) for archival purposes.
</Tip>

<Note>
  **Permission Requirements**: You can only delete projects that belong to your account or team. Attempting to delete projects from other accounts will result in a 403 Forbidden error.
</Note>

***

## Common Use Cases

### 1. Delete Single Project with Confirmation

Delete a project after user confirmation:

```python theme={null}
import requests

def delete_project_with_confirmation(project_id, api_key):
    """
    Delete a project after confirming with the user
    """
    # First, get project details
    get_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    headers = {"Authorization": api_key}

    project_response = requests.get(get_url, headers=headers)

    if project_response.status_code != 200:
        print("Project not found")
        return False

    project = project_response.json()
    project_name = project.get('projectName', 'Unknown')

    # Confirm deletion
    print(f"Are you sure you want to delete '{project_name}'? (yes/no)")
    confirmation = input().strip().lower()

    if confirmation != 'yes':
        print("Deletion cancelled")
        return False

    # Delete project
    delete_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    delete_response = requests.delete(delete_url, headers=headers)
    result = delete_response.json()

    if result.get('success'):
        print(f"Project '{project_name}' deleted successfully")
        return True
    else:
        print(f"Failed to delete project: {result.get('message')}")
        return False

# Example usage
delete_project_with_confirmation("YOUR_PROJECT_ID", "YOUR_API_KEY")
```

### 2. Bulk Delete Old Projects

Delete multiple projects based on age criteria:

```python theme={null}
from datetime import datetime, timedelta
import requests

def delete_old_projects(days_old, api_key, dry_run=True):
    """
    Delete projects older than specified number of days
    """
    headers = {"Authorization": api_key}

    # Get all projects
    list_url = "https://api.pictory.ai/pictoryapis/v2/projects"
    response = requests.get(list_url, headers=headers)
    projects = response.json().get('items', [])

    # Calculate cutoff date
    cutoff = datetime.now() - timedelta(days=days_old)

    # Find old projects
    old_projects = []
    for project in projects:
        saved_date = datetime.fromisoformat(project['savedDate'].replace('Z', '+00:00'))
        if saved_date < cutoff:
            old_projects.append(project)

    print(f"Found {len(old_projects)} projects older than {days_old} days")

    if dry_run:
        print("DRY RUN - Projects that would be deleted:")
        for project in old_projects:
            print(f"  - {project['name']} (saved: {project['savedDate']})")
        return

    # Delete old projects
    deleted_count = 0
    for project in old_projects:
        delete_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project['id']}"
        delete_response = requests.delete(delete_url, headers=headers)

        if delete_response.json().get('success'):
            print(f"Deleted: {project['name']}")
            deleted_count += 1
        else:
            print(f"Failed to delete: {project['name']}")

    print(f"Deleted {deleted_count} out of {len(old_projects)} old projects")

# Example usage - dry run first
delete_old_projects(days_old=90, api_key="YOUR_API_KEY", dry_run=True)

# Then execute for real
# delete_old_projects(days_old=90, api_key="YOUR_API_KEY", dry_run=False)
```

### 3. Delete Projects by Source Type

Delete all projects created from a specific source:

```javascript theme={null}
async function deleteProjectsBySource(sourceType, apiKey, confirmAll = false) {
  const headers = { 'Authorization': `${apiKey}` };

  // Get all projects
  const listResponse = await fetch(
    'https://api.pictory.ai/pictoryapis/v2/projects',
    { headers }
  );
  const data = await listResponse.json();

  // Filter by source type
  const matchingProjects = data.items.filter(p => p.source === sourceType);

  console.log(`Found ${matchingProjects.length} projects with source: ${sourceType}`);

  if (!confirmAll) {
    console.log('Set confirmAll=true to delete these projects');
    return matchingProjects;
  }

  // Delete matching projects
  const results = {
    deleted: [],
    failed: []
  };

  for (const project of matchingProjects) {
    const deleteResponse = await fetch(
      `https://api.pictory.ai/pictoryapis/v2/projects/${project.id}`,
      { method: 'DELETE', headers }
    );

    const result = await deleteResponse.json();

    if (result.success) {
      results.deleted.push(project.name);
      console.log(`✓ Deleted: ${project.name}`);
    } else {
      results.failed.push(project.name);
      console.log(`✗ Failed: ${project.name}`);
    }
  }

  console.log(`\nDeleted: ${results.deleted.length}, Failed: ${results.failed.length}`);
  return results;
}

// Example usage
const results = await deleteProjectsBySource('url', 'YOUR_API_KEY', true);
```

### 4. Back Up Before Delete

Back up project assets before deletion:

```python theme={null}
import requests
import os

def backup_and_delete_project(project_id, api_key, backup_dir="./backups"):
    """
    Backup project assets before deleting
    """
    headers = {"Authorization": api_key}

    # Get project details
    get_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    response = requests.get(get_url, headers=headers)

    if response.status_code != 200:
        print("Project not found")
        return False

    project = response.json()
    project_name = project.get('projectName', project_id)

    # Create backup directory
    project_backup_dir = os.path.join(backup_dir, project_name)
    os.makedirs(project_backup_dir, exist_ok=True)

    print(f"Backing up project: {project_name}")

    # Backup assets
    assets = {
        'video': project.get('videoURL'),
        'audio': project.get('audioURL'),
        'srt': project.get('srtFile'),
        'vtt': project.get('vttFile'),
        'txt': project.get('txtFile'),
        'thumbnail': project.get('thumbnail')
    }

    backed_up = []
    for asset_type, url in assets.items():
        if url:
            try:
                file_response = requests.get(url)
                extension = asset_type if asset_type in ['srt', 'vtt', 'txt'] else url.split('.')[-1].split('?')[0]
                filename = f"{project_name}_{asset_type}.{extension}"
                filepath = os.path.join(project_backup_dir, filename)

                with open(filepath, 'wb') as f:
                    f.write(file_response.content)

                backed_up.append(asset_type)
                print(f"  ✓ Backed up {asset_type}")
            except Exception as e:
                print(f"  ✗ Failed to backup {asset_type}: {e}")

    # Save project metadata
    import json
    metadata_path = os.path.join(project_backup_dir, "metadata.json")
    with open(metadata_path, 'w') as f:
        json.dump(project, f, indent=2)

    print(f"Backup complete: {len(backed_up)} assets saved to {project_backup_dir}")

    # Delete project
    print(f"Deleting project...")
    delete_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    delete_response = requests.delete(delete_url, headers=headers)
    result = delete_response.json()

    if result.get('success'):
        print(f"Project '{project_name}' deleted successfully")
        return True
    else:
        print(f"Failed to delete project: {result.get('message')}")
        return False

# Example usage
backup_and_delete_project("YOUR_PROJECT_ID", "YOUR_API_KEY")
```

### 5. Safe Delete with Retry Logic

Delete project with error handling and retry:

```javascript theme={null}
async function safeDeleteProject(projectId, apiKey, maxRetries = 3) {
  const headers = { 'Authorization': `${apiKey}` };

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      console.log(`Attempt ${attempt} to delete project ${projectId}...`);

      const response = await fetch(
        `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
        { method: 'DELETE', headers }
      );

      if (response.status === 401) {
        throw new Error('Unauthorized - check your API key');
      }

      if (response.status === 404) {
        console.log('Project already deleted or does not exist');
        return { success: true, message: 'Project not found' };
      }

      const result = await response.json();

      if (result.success) {
        console.log('Project deleted successfully');
        return result;
      }

      if (attempt < maxRetries) {
        console.log(`Deletion failed, retrying in ${attempt * 2} seconds...`);
        await new Promise(resolve => setTimeout(resolve, attempt * 2000));
      }
    } catch (error) {
      console.error(`Error on attempt ${attempt}:`, error.message);

      if (attempt === maxRetries) {
        throw error;
      }

      await new Promise(resolve => setTimeout(resolve, attempt * 2000));
    }
  }

  throw new Error(`Failed to delete project after ${maxRetries} attempts`);
}

// Example usage
try {
  const result = await safeDeleteProject('YOUR_PROJECT_ID', 'YOUR_API_KEY');
  console.log('Result:', result);
} catch (error) {
  console.error('Final error:', error.message);
}
```

### 6. Delete Projects in Specific Folder

Delete all projects within a specific folder:

```python theme={null}
def delete_folder_projects(folder_id, api_key, confirm=False):
    """
    Delete all projects within a specific folder
    """
    headers = {"Authorization": api_key}

    # Get projects in folder
    list_url = f"https://api.pictory.ai/pictoryapis/v2/projects?folder={folder_id}"
    response = requests.get(list_url, headers=headers)
    projects = response.json().get('items', [])

    print(f"Found {len(projects)} projects in folder {folder_id}")

    if not projects:
        print("No projects to delete")
        return

    # List projects
    for i, project in enumerate(projects, 1):
        print(f"{i}. {project['name']} (ID: {project['id']})")

    if not confirm:
        print("\nSet confirm=True to delete these projects")
        return

    # Delete projects
    deleted_count = 0
    for project in projects:
        delete_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project['id']}"
        delete_response = requests.delete(delete_url, headers=headers)

        if delete_response.json().get('success'):
            print(f"✓ Deleted: {project['name']}")
            deleted_count += 1
        else:
            print(f"✗ Failed: {project['name']}")

    print(f"\nDeleted {deleted_count} out of {len(projects)} projects")

# Example usage
delete_folder_projects("your-folder-id", "YOUR_API_KEY", confirm=True)
```

***

## Best Practices

### Safety Measures

1. **Always back up before deletion**: Use the Get Project By Id endpoint to retrieve all assets before deleting
2. **Implement confirmation**: Require user confirmation before executing delete operations
3. **Use dry runs**: Test deletion logic with dry run mode before executing
4. **Log deletions**: Keep audit logs of deleted projects for accountability
5. **Handle errors gracefully**: Implement proper error handling and retry logic

### Bulk Operations

When deleting multiple projects:

* Add delays between deletions to avoid rate limiting
* Process deletions in batches
* Implement comprehensive error handling
* Provide progress updates to users
* Log both successes and failures

### Recovery Planning

Since deletion is permanent:

* Maintain regular backups of important projects
* Export project metadata before deletion
* Download all media files (video, audio, subtitles) for archival
* Keep deletion logs for audit trails