Quick Start Guide

Get started with MarkdownAPI.io in 5 minutes. This guide walks you through authentication, creating a project, and managing files.

Step 1: Get Your Credentials

First, sign up at markdownapi.io and create an API key through the dashboard:

Navigate to Dashboard → API Keys
Enter a descriptive name (e.g., “Development Key”)
Click “Create API Key”
Important: Copy the key from the modal immediately - it’s only shown once!
Save it securely in your environment variables

Critical: The API key is displayed only once and cannot be retrieved later. If you close the modal without copying it, you’ll need to create a new key.

Store your API key as an environment variable:


export MARKDOWN_API_KEY="sk_your_api_key_here"

Need more details? See the complete Authentication Guide for step-by-step instructions with screenshots and security best practices.

Step 2: Create a Project

Create your first project to organize files:


import httpx
import os
 
async def create_project():
    api_key = os.getenv("MARKDOWN_API_KEY")
 
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://markdownapi.io/api/projects",
            headers={"Authorization": f"Bearer {api_key}"},
            json={
                "name": "My First Project",
                "description": "Learning MarkdownAPI.io"
            }
        )
 
        project = response.json()
        print(f"Created project: {project['id']}")
        return project['id']
 
# Save project ID for next steps
project_id = await create_project()

Step 3: Upload a File

Upload your first Markdown file:


async def upload_file(project_id: str):
    api_key = os.getenv("MARKDOWN_API_KEY")
 
    # Create a simple markdown file
    content = b"# Hello World\n\nThis is my first file on MarkdownAPI.io!"
 
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"https://markdownapi.io/api/projects/{project_id}/files",
            headers={"Authorization": f"Bearer {api_key}"},
            files={'file': ('hello.md', content, 'text/markdown')},
            data={'metadata': '{"status": "draft"}'}
        )
 
        file_info = response.json()
        print(f"Uploaded: {file_info['filename']}")
        return file_info
 
await upload_file(project_id)

Step 4: List Files

View all files in your project:


async def list_files(project_id: str):
    api_key = os.getenv("MARKDOWN_API_KEY")
 
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://markdownapi.io/api/projects/{project_id}/files",
            headers={"Authorization": f"Bearer {api_key}"}
        )
 
        data = response.json()
        print(f"Found {data['total_count']} files:")
        for file in data['files']:
            print(f"  • {file['filename']}")
 
await list_files(project_id)

Step 5: Download a File

Retrieve file content:


async def download_file(project_id: str, filename: str):
    api_key = os.getenv("MARKDOWN_API_KEY")
 
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://markdownapi.io/api/projects/{project_id}/files/{filename}",
            headers={"Authorization": f"Bearer {api_key}"}
        )
 
        content = response.content
        print(content.decode('utf-8'))
        return content
 
await download_file(project_id, "hello.md")

Complete Example

Here’s everything together in a complete Python script:


import httpx
import os
import asyncio
 
async def quickstart():
    """Complete quickstart example."""
    api_key = os.getenv("MARKDOWN_API_KEY")
 
    async with httpx.AsyncClient() as client:
        # 1. Create project
        project_response = await client.post(
            "https://markdownapi.io/api/projects",
            headers={"Authorization": f"Bearer {api_key}"},
            json={
                "name": "My First Project",
                "description": "Learning MarkdownAPI.io"
            }
        )
        project = project_response.json()
        project_id = project['id']
        print(f"✓ Created project: {project['name']}")
 
        # 2. Upload file
        content = b"# Hello World\n\nThis is my first file!"
        upload_response = await client.post(
            f"https://markdownapi.io/api/projects/{project_id}/files",
            headers={"Authorization": f"Bearer {api_key}"},
            files={'file': ('hello.md', content, 'text/markdown')},
            data={'metadata': '{"status": "draft"}'}
        )
        file_info = upload_response.json()
        print(f"✓ Uploaded: {file_info['filename']}")
 
        # 3. List files
        list_response = await client.get(
            f"https://markdownapi.io/api/projects/{project_id}/files",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        files_data = list_response.json()
        print(f"✓ Found {files_data['total_count']} files")
 
        # 4. Download file
        download_response = await client.get(
            f"https://markdownapi.io/api/projects/{project_id}/files/hello.md",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        downloaded_content = download_response.content
        print(f"✓ Downloaded content:\n{downloaded_content.decode('utf-8')}")
 
# Run it
asyncio.run(quickstart())

TypeScript Example


import 'dotenv/config';
 
async function quickstart() {
  const apiKey = process.env.MARKDOWN_API_KEY!;
  const baseUrl = 'https://markdownapi.io/api';
 
  // 1. Create project
  const projectRes = await fetch(`${baseUrl}/projects`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'My First Project',
      description: 'Learning MarkdownAPI.io'
    }),
  });
  const project = await projectRes.json();
  console.log(`✓ Created project: ${project.name}`);
 
  // 2. Upload file
  const formData = new FormData();
  formData.append('file', new Blob(['# Hello World\n\nMy first file!']), 'hello.md');
  formData.append('metadata', JSON.stringify({ status: 'draft' }));
 
  const uploadRes = await fetch(`${baseUrl}/projects/${project.id}/files`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${apiKey}` },
    body: formData,
  });
  const fileInfo = await uploadRes.json();
  console.log(`✓ Uploaded: ${fileInfo.filename}`);
 
  // 3. List files
  const listRes = await fetch(`${baseUrl}/projects/${project.id}/files`, {
    headers: { 'Authorization': `Bearer ${apiKey}` },
  });
  const filesData = await listRes.json();
  console.log(`✓ Found ${filesData.total_count} files`);
 
  // 4. Download file
  const downloadRes = await fetch(
    `${baseUrl}/projects/${project.id}/files/hello.md`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  const content = await downloadRes.text();
  console.log(`✓ Downloaded content:\n${content}`);
}
 
quickstart();

Next Steps

AI Agent Integration - Build AI agent workflows
Error Handling - Handle errors properly
API Reference - Detailed API documentation