Projects API Overview

The Projects API allows you to organize your Markdown and MDX files into isolated workspaces. Each project has its own Google Cloud Storage bucket, statistics tracking, and independent file namespace.

What is a Project?

A project is a container for related files with the following characteristics:

• Unique Name: Each project must have a unique name within your account
• Isolated Storage: Each project gets its own GCS bucket for file storage
• Statistics Tracking: Automatic tracking of file count and total size
• Default Project: Every account has one default project created automatically
• Soft Deletion: Projects can be soft-deleted (marked inactive) or hard-deleted (permanently removed)

Project Lifecycle

Create → Active → [Update] → Delete → Removed
   ↓                           ↓
Default Project         Soft Delete (inactive)
(auto-created)          Hard Delete (removed)

Lifecycle States

1. Creation: Projects are created with a unique name and optional description
2. Active: Normal operational state - files can be uploaded and managed
3. Updated: Name and description can be modified at any time
4. Soft Deleted: Marked as inactive (is_active=false) - can be reactivated
5. Hard Deleted: Permanently removed along with all files and GCS bucket

Project Properties

Default Project

Every account automatically gets a default project on first login:

• Name: "Default Project" or "default"
• is_default: true
• Created automatically if no projects exist
• Cannot be deleted (returns error)
• Ideal for quick testing and single-project use cases

Storage Architecture

Each project uses a dedicated Google Cloud Storage bucket:

Bucket Naming:

markdown-api-{user_id}-{project_id}

Benefits:

• Isolated storage per project
• Independent access control
• Easy project-level backups
• Simple cleanup on deletion

File Paths:

gs://markdown-api-user123-proj456/document.md
gs://markdown-api-user123-proj456/folder/article.mdx

Statistics Tracking

Projects automatically track usage statistics:

• file_count: Incremented on upload, decremented on delete
• total_size_bytes: Updated on upload, update, and delete operations
• Real-time updates: Statistics updated immediately on file operations

Example:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "AI Articles",
  "file_count": 42,
  "total_size_bytes": 2097152  // 2 MB
}

Naming Rules

Project names must follow these rules:

• Length: 1-255 characters
• Uniqueness: Must be unique within your account
• Characters: Any UTF-8 characters allowed
• Case-sensitive: “Project” and “project” are different
• Reserved names: Cannot use “default” if default project exists

Valid names:

"My Project"
"AI Articles 2025"
"项目一" (Chinese characters)
"Проект" (Cyrillic)

Invalid operations:

• Creating duplicate names (409 Conflict)
• Empty names (400 Bad Request)
• Names over 255 characters (422 Validation Error)

Common Use Cases

1. Content Organization

Organize content by purpose or client:

Projects:
- "Blog Articles"      → All blog posts
- "Documentation"      → API/product docs
- "Client ABC"         → Client-specific content
- "AI Agent Memory"    → Agent conversation history

2. Environment Separation

Separate development and production content:

Projects:
- "Development"   → Test content
- "Staging"       → Review content
- "Production"    → Live content

3. Temporal Organization

Organize by time period:

Projects:
- "Q1 2025 Content"
- "Q2 2025 Content"
- "Archive 2024"

4. Agent Workspaces

Give each AI agent its own project:

Projects:
- "Agent-Writer"     → Content generation agent
- "Agent-Summarizer" → Summary agent
- "Agent-Memory"     → Long-term memory storage

Performance Considerations

Project Limits

• Projects per account: Unlimited (soft limit: 1000)
• Files per project: Unlimited (soft limit: 100,000)
• Total size per project: Unlimited (soft limit: 100 GB)

Exceeding soft limits may require account upgrade.

Operation Speed

Optimization Tips

1. Cache project lists: Projects change infrequently - cache for 5-10 minutes
2. Reuse projects: Creating many projects is expensive - reuse when possible
3. Batch operations: Group file operations within same project
4. Monitor statistics: Use file_count and total_size_bytes for capacity planning

Best Practices

Naming Conventions

Use consistent, descriptive names:

# Good
"Blog Articles 2025"
"Client ABC - Marketing Content"
"Agent Memory - Production"
 
# Avoid
"Project 1"
"Test"
"asdf"

Project Structure

Organize projects logically:

# By purpose (recommended)
- Content Generation
- Agent Memory
- Documentation
- Archive

# By environment
- Development
- Staging
- Production

# By client (for agencies)
- Client A
- Client B
- Internal

Cleanup Strategy

Regularly clean up unused projects:

1. Identify inactive projects: No file uploads in 90+ days
2. Archive if needed: Download files before deletion
3. Soft delete first: Mark inactive to test impact
4. Hard delete after confirmation: Permanent removal

Security Considerations

1. Access control: Projects are user-scoped - no sharing (yet)
2. Bucket isolation: Each project has isolated storage
3. Soft delete: Use soft delete for recoverable deletion
4. Audit trail: Track created_date and updated_date

API Endpoints

Available Operations

Quick Reference

Error Scenarios

Common Errors

Edge Cases

1. Deleting default project: Returns 403 Forbidden
2. Updating to duplicate name: Returns 409 Conflict
3. Deleting project with files: All files deleted (use with caution)
4. Creating while rate limited: Returns 429 - retry with backoff

Migration and Import

Moving Files Between Projects

Projects don’t support direct file moves. To move files:

1. Download files from source project
2. Upload files to destination project
3. Verify upload succeeded
4. Delete files from source project

Bulk Import

For bulk imports, use parallel uploads:

import asyncio
import httpx
 
async def bulk_upload(api_key, project_id, files):
    async with httpx.AsyncClient() as client:
        tasks = [
            upload_file(client, api_key, project_id, file_path)
            for file_path in files
        ]
        results = await asyncio.gather(*tasks)
    return results

Monitoring and Observability

Key Metrics to Track

1. Project count: Monitor growth over time
2. Files per project: Identify large projects
3. Storage per project: Track storage consumption
4. Creation rate: Detect unusual activity
5. Deletion rate: Monitor cleanup patterns

Alerting Recommendations

Set up alerts for:

• Projects approaching 100k files
• Projects approaching 100 GB
• Unusual creation/deletion patterns
• Failed operations (5xx errors)

Next Steps

• Create Project - Learn how to create projects
• Files API - Manage files within projects
• Quick Start Guide - Complete tutorial
• Core Concepts - Deep dive into project concepts