Update File Metadata

Update the metadata of an existing file without changing its content. Useful for adding or modifying tags, titles, authors, and other custom fields.

Endpoint


PUT /api/projects/{project_id}/files/{filename}

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
`filename`	string	Yes	The exact filename (case-sensitive)

Request Body


{
  "metadata": {
    "title": "Updated Title",
    "author": "Jane Doe",
    "tags": ["ai", "tutorial", "advanced"],
    "status": "published"
  }
}

Important: Metadata is completely replaced, not merged.

Response

Success Response (200 OK)


{
  "filename": "article.mdx",
  "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "size_bytes": 4096,
  "metadata": {
    "title": "Updated Title",
    "author": "Jane Doe",
    "tags": ["ai", "tutorial", "advanced"]
  },
  "updated_date": "2025-01-09T15:00:00Z"
}

Error Responses

Status	Error	Description
400	Bad Request	Invalid JSON
401	Unauthorized	Invalid authentication
404	Not Found	File does not exist
422	Unprocessable Entity	Invalid metadata format

Examples

cURL


curl -X PUT "https://markdownapi.io/api/projects/PROJECT_ID/files/article.mdx" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"title": "Updated", "author": "Jane Doe"}}'

Python (httpx)


async def update_file_metadata(project_id: str, filename: str, metadata: dict | None):
    api_key = os.getenv("MARKDOWN_API_KEY")
 
    async with httpx.AsyncClient() as client:
        response = await client.put(
            f"https://markdownapi.io/api/projects/{project_id}/files/{filename}",
            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
            json={"metadata": metadata},
            timeout=30.0
        )
 
        response.raise_for_status()
        return response.json()

TypeScript


async function updateFileMetadata(
  projectId: string,
  filename: string,
  metadata: Record<string, any> | null
): Promise<any> {
  const response = await fetch(
    `https://markdownapi.io/api/projects/${projectId}/files/${filename}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${process.env.MARKDOWN_API_KEY!}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ metadata }),
    }
  );
 
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return await response.json();
}

Best Practices

Always merge with existing metadata:


# Get current metadata first
files = await list_files(project_id)
file_info = next(f for f in files['files'] if f['filename'] == filename)
existing = file_info.get('metadata') or {}
 
# Merge with new data
merged = {**existing, **new_metadata}
await update_file_metadata(project_id, filename, merged)

Use consistent schema across all files
Include timestamps for tracking changes
Validate metadata before updating