List Files

Retrieve a list of all files in a project. Returns file metadata including name, size, and creation date.

Endpoint


GET /api/projects/{project_id}/files

Authentication

Required: API key in Authorization header


Authorization: Bearer YOUR_API_KEY

Request

Path Parameters

Parameter	Type	Required	Description
`project_id`	UUID	Yes	The project ID

Headers

Header	Value	Required
`Authorization`	`Bearer YOUR_API_KEY`	Yes

Query Parameters

No query parameters supported. Returns all files in the project.

Response

Success Response (200 OK)


{
  "files": [
    {
      "filename": "article-1.mdx",
      "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "size_bytes": 4096,
      "content_type": "text/markdown",
      "metadata": {
        "title": "Introduction",
        "author": "John Doe"
      },
      "storage_path": "gs://markdown-api-user123-a1b2c3d4/article-1.mdx",
      "created_date": "2025-01-09T10:00:00Z",
      "updated_date": "2025-01-09T10:00:00Z"
    },
    {
      "filename": "article-2.md",
      "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "size_bytes": 2048,
      "content_type": "text/markdown",
      "metadata": null,
      "storage_path": "gs://markdown-api-user123-a1b2c3d4/article-2.md",
      "created_date": "2025-01-09T11:00:00Z",
      "updated_date": "2025-01-09T11:00:00Z"
    }
  ],
  "total_count": 2,
  "total_size_bytes": 6144
}

Response Fields

Field	Type	Description
`files`	array	List of file objects
`total_count`	integer	Total number of files in project
`total_size_bytes`	integer	Combined size of all files

File Object Fields

Field	Type	Description
`filename`	string	Name of the file
`project_id`	UUID	Project containing the file
`size_bytes`	integer	File size in bytes
`content_type`	string	MIME type (text/markdown)
`metadata`	object\|null	Custom metadata
`storage_path`	string	GCS storage path
`created_date`	datetime	When file was uploaded (ISO 8601 UTC)
`updated_date`	datetime	When file was last modified (ISO 8601 UTC)

Error Responses

Status	Error	Description	Solution
401	Unauthorized	Missing or invalid authentication	Verify Bearer token or API key is valid
404	Not Found	Project does not exist	Verify project_id is correct
429	Too Many Requests	Rate limit exceeded	Wait and retry with exponential backoff
500	Internal Server Error	Server error	Contact support if error persists

Example Error Response (404 Not Found):


{
  "detail": "Project not found"
}

Examples

cURL


curl "https://markdownapi.io/api/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python (httpx)


import httpx
import os
 
async def list_files(project_id: str):
    """List all files in a project."""
 
    api_key = os.getenv("MARKDOWN_API_KEY")
 
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(
                f"https://markdownapi.io/api/projects/{project_id}/files",
                headers={"Authorization": f"Bearer {api_key}"},
                timeout=30.0
            )
 
            response.raise_for_status()
            data = response.json()
 
            print(f"✓ Found {data['total_count']} files")
            print(f"  Total size: {data['total_size_bytes']:,} bytes")
 
            for file in data['files']:
                print(f"  - {file['filename']} ({file['size_bytes']:,} bytes)")
 
            return data
 
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 404:
                print(f"✗ Project not found")
            else:
                print(f"✗ HTTP error: {e.response.status_code}")
            raise
        except httpx.TimeoutException:
            print(f"✗ Request timed out")
            raise
        except Exception as e:
            print(f"✗ Unexpected error: {e}")
            raise
 
# Usage
# files = await list_files("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

TypeScript


interface FileInfo {
  filename: string;
  project_id: string;
  size_bytes: number;
  content_type: string;
  metadata: Record<string, any> | null;
  storage_path: string;
  created_date: string;
  updated_date: string;
}
 
interface ListFilesResponse {
  files: FileInfo[];
  total_count: number;
  total_size_bytes: number;
}
 
async function listFiles(projectId: string): Promise<ListFilesResponse> {
  const apiKey = process.env.MARKDOWN_API_KEY;
 
  try {
    const response = await fetch(
      `https://markdownapi.io/api/projects/${projectId}/files`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`,
        },
      }
    );
 
    if (!response.ok) {
      if (response.status === 404) {
        throw new Error('Project not found');
      }
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
 
    const data: ListFilesResponse = await response.json();
 
    console.log(`✓ Found ${data.total_count} files`);
    console.log(`  Total size: ${data.total_size_bytes.toLocaleString()} bytes`);
 
    data.files.forEach((file) => {
      console.log(`  - ${file.filename} (${file.size_bytes.toLocaleString()} bytes)`);
    });
 
    return data;
 
  } catch (error) {
    console.error('✗ Failed to list files:', error);
    throw error;
  }
}
 
// Usage
// const files = await listFiles('a1b2c3d4-e5f6-7890-abcd-ef1234567890');