API Reference

Complete reference documentation for the MarkdownAPI.io REST API. All endpoints require authentication via API key.

Base URL

https://markdownapi.io/api

All API requests must be made over HTTPS. HTTP requests will be redirected to HTTPS.

Authentication

Every API request must include an API key:

Authorization: Bearer YOUR_API_KEY

See the Authentication Guide for detailed information on obtaining and using API keys.

API Structure

The API is organized into two main resource categories:

Projects API

Manage your projects and their settings. Each project provides an isolated workspace with its own Google Cloud Storage bucket.

• Create Project - POST /api/projects
• List Projects - GET /api/projects
• Get Project - GET /api/projects/{id}
• Update Project - PUT /api/projects/{id}
• Delete Project - DELETE /api/projects/{id}

Files API

Manage files within your projects. Upload, download, and manage Markdown and MDX files with custom metadata support.

• Upload File - POST /api/projects/{project_id}/files
• List Files - GET /api/projects/{project_id}/files
• Download File - GET /api/projects/{project_id}/files/{filename}
• Update Metadata - PUT /api/projects/{project_id}/files/{filename}
• Update Content - PUT /api/projects/{project_id}/files/{filename}/content
• Delete File - DELETE /api/projects/{project_id}/files/{filename}

Request Format

All requests with bodies must use one of these content types:

• JSON: Content-Type: application/json for metadata operations
• Multipart: Content-Type: multipart/form-data for file uploads

Response Format

All responses are returned in JSON format with appropriate HTTP status codes:

Success Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Project",
  "created_date": "2025-01-09T10:00:00Z"
}

Error Response:

{
  "detail": "Descriptive error message"
}

HTTP Status Codes

The API uses standard HTTP status codes:

Data Types

Common data types used across the API:

Date and Time

All timestamps are in UTC and follow ISO 8601 format:

2025-01-09T10:00:00Z

The Z suffix indicates UTC timezone. When submitting datetime values, either include explicit timezone or they will be interpreted as UTC.

Pagination

Currently, list endpoints return all results without pagination. Future versions may introduce pagination with limit, offset, and cursor parameters.

Current Response:

{
  "projects": [...],
  "total_count": 42
}

Error Handling

The API returns descriptive error messages to help diagnose issues:

Validation Errors (400, 422)

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Authentication Errors (401)

{
  "detail": "Invalid authentication credentials"
}

Permission Errors (403)

{
  "detail": "You do not have permission to access this resource"
}

Not Found Errors (404)

{
  "detail": "Project not found"
}

Conflict Errors (409)

{
  "detail": "File with name 'document.md' already exists in project"
}

Rate Limiting

Rate limits are applied per account and API key:

• Standard Accounts: 1000 requests/hour
• Premium Accounts: 10000 requests/hour

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1704801600

When rate limited (HTTP 429):

{
  "detail": "Rate limit exceeded. Try again in 3456 seconds."
}

Idempotency

Most mutation endpoints (POST, PUT, DELETE) are not idempotent by default. Creating the same resource twice will result in duplicates or conflicts.

Exceptions:

• PUT endpoints are idempotent - repeating the same update yields the same result
• DELETE endpoints return 404 if resource is already deleted

Concurrency

The API handles concurrent requests safely:

• File uploads with duplicate names return 409 Conflict
• Concurrent updates to the same resource use last-write-wins
• Project deletion is atomic - all files deleted before bucket removal

Versioning

The current API is version 1 (implicit). Future versions may introduce explicit versioning in the URL path or headers.

Current: https://markdownapi.io/api/projects

Future (example): https://markdownapi.io/api/v2/projects

SDKs and Tools

Official SDKs and tools:

• Python SDK: Coming soon
• TypeScript SDK: Coming soon
• CLI Tool: Coming soon

Best Practices

1. Always include authentication - Every request requires an API key
2. Check HTTP status codes - Don’t just check for 200, handle all error codes
3. Use appropriate content types - JSON for metadata, multipart for file uploads
4. Implement retry logic - Use exponential backoff for 429 and 5xx errors
5. Cache responses - Reduce API calls by caching project/file lists when appropriate
6. Monitor rate limits - Check rate limit headers and throttle requests proactively
7. Handle errors gracefully - Parse error responses and show user-friendly messages
8. Use UUIDs for identifiers - Projects and files use UUIDs, not integer IDs
9. Validate before uploading - Check file types (.md, .mdx only) before API calls
10. Close connections - Properly close HTTP connections to avoid resource leaks

Next Steps

• Projects API Overview - Learn about project management
• Files API Overview - Learn about file management
• Quick Start Guide - Complete tutorial
• Authentication Guide - Detailed authentication documentation