API Documentation

gitmd2pdf provides a RESTful API for programmatic markdown-to-PDF conversion. The API uses OAuth 2.0 client credentials for authentication and supports asynchronous job processing with optional webhooks.

Authentication

The API uses OAuth 2.0 client credentials flow. You'll need a Premium subscription to access the API.

Getting API Credentials

1. Log in to your gitmd2pdf account
2. Navigate to Account > API Keys
3. Click Generate New Credentials
4. Save your client_id and client_secret securely

Obtaining an Access Token

curl -X POST https://gitmd2pdf.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the access token in subsequent requests:

Authorization: Bearer <access_token>

Endpoints

POST /api/v1/convert

Enqueue a markdown-to-PDF conversion job.

Authentication: Required (Bearer token)

Content-Type: application/json or multipart/form-data (for file uploads)

Request Body

Example: Convert a File

curl -X POST https://gitmd2pdf.com/api/v1/convert \
  -H "Authorization: Bearer <access_token>" \
  -F "type=file" \
  -F "file=@README.md" \
  -F "title=My Documentation"

Example: Convert a Repository

curl -X POST https://gitmd2pdf.com/api/v1/convert \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "repo",
    "repoUrl": "https://github.com/user/repo",
    "branch": "main",
    "title": "Project Documentation"
  }'

Example: Convert a URL

curl -X POST https://gitmd2pdf.com/api/v1/convert \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://raw.githubusercontent.com/user/repo/main/README.md"
  }'

Response (202 Accepted):

{
  "jobId": "job_abc123def456",
  "status": "queued"
}

GET /api/v1/jobs/:jobId/status

Check the status of a conversion job.

Authentication: Required (Bearer token)

Response:

{
  "jobId": "job_abc123def456",
  "status": "completed",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:30:15Z"
}

Status Values:

• queued - Job is waiting to be processed
• processing - Job is currently being converted
• completed - Conversion successful, PDF ready for download
• failed - Conversion failed (see error field)

GET /api/v1/jobs/:jobId/download

Download the converted PDF file.

Authentication: Required (Bearer token)

Response: Binary PDF file with Content-Type: application/pdf

curl -X GET https://gitmd2pdf.com/api/v1/jobs/job_abc123def456/download \
  -H "Authorization: Bearer <access_token>" \
  -o output.pdf

Webhooks

For asynchronous workflows, configure a callback URL to receive job completion notifications.

Setting Up Webhooks

1. Add callback domain to allowlist:

curl -X POST https://gitmd2pdf.com/api/v1/callback-allowlist \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "api.yourapp.com"}'

2. Include callback URL in conversion request:

curl -X POST https://gitmd2pdf.com/api/v1/convert \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "repo",
    "repoUrl": "https://github.com/user/repo",
    "callbackUrl": "https://api.yourapp.com/webhooks/gitmd2pdf",
    "callbackAuthHeader": "Bearer your-webhook-secret"
  }'

Webhook Payload

{
  "jobId": "job_abc123def456",
  "status": "completed",
  "downloadUrl": "https://gitmd2pdf.com/api/v1/jobs/job_abc123def456/download"
}

Managing Callback Allowlist

List allowed domains:

GET /api/v1/callback-allowlist

Remove a domain:

DELETE /api/v1/callback-allowlist/:domain

API Credentials Management

POST /api/v1/credentials

Generate new API credentials.

Authentication: Required (Session token)

GET /api/v1/credentials

List your API credentials.

Authentication: Required (Session token)

DELETE /api/v1/credentials/:clientId

Revoke API credentials.

Authentication: Required (Session token)

Rate Limits

Rate limit headers are included in all responses:

• X-RateLimit-Limit - Maximum requests per window
• X-RateLimit-Remaining - Requests remaining
• X-RateLimit-Reset - Unix timestamp when the limit resets

Error Responses

All errors follow a consistent format:

{
  "error": "Error message describing the issue"
}

OpenAPI Specification

The complete OpenAPI 3.0 specification is available at:

GET /api/v1/openapi.json

You can import this into tools like Postman, Insomnia, or Swagger UI for interactive API exploration.

Code Examples

Python

import requests

# Get access token
auth_response = requests.post(
    "https://gitmd2pdf.com/api/v1/oauth/token",
    json={
        "grant_type": "client_credentials",
        "client_id": "your_client_id",
        "client_secret": "your_client_secret"
    }
)
token = auth_response.json()["access_token"]

# Convert a repository
headers = {"Authorization": f"Bearer {token}"}
convert_response = requests.post(
    "https://gitmd2pdf.com/api/v1/convert",
    headers=headers,
    json={
        "type": "repo",
        "repoUrl": "https://github.com/user/repo"
    }
)
job_id = convert_response.json()["jobId"]

# Poll for completion
import time
while True:
    status = requests.get(
        f"https://gitmd2pdf.com/api/v1/jobs/{job_id}/status",
        headers=headers
    ).json()
    if status["status"] == "completed":
        break
    time.sleep(2)

# Download PDF
pdf = requests.get(
    f"https://gitmd2pdf.com/api/v1/jobs/{job_id}/download",
    headers=headers
)
with open("output.pdf", "wb") as f:
    f.write(pdf.content)

Node.js

const axios = require('axios');
const fs = require('fs');

async function convertRepo(repoUrl) {
  // Get access token
  const { data: auth } = await axios.post(
    'https://gitmd2pdf.com/api/v1/oauth/token',
    {
      grant_type: 'client_credentials',
      client_id: process.env.GITMD2PDF_CLIENT_ID,
      client_secret: process.env.GITMD2PDF_CLIENT_SECRET
    }
  );

  const headers = { Authorization: `Bearer ${auth.access_token}` };

  // Start conversion
  const { data: job } = await axios.post(
    'https://gitmd2pdf.com/api/v1/convert',
    { type: 'repo', repoUrl },
    { headers }
  );

  // Poll for completion
  let status;
  do {
    await new Promise(r => setTimeout(r, 2000));
    const { data } = await axios.get(
      `https://gitmd2pdf.com/api/v1/jobs/${job.jobId}/status`,
      { headers }
    );
    status = data.status;
  } while (status !== 'completed' && status !== 'failed');

  // Download PDF
  const pdf = await axios.get(
    `https://gitmd2pdf.com/api/v1/jobs/${job.jobId}/download`,
    { headers, responseType: 'arraybuffer' }
  );

  fs.writeFileSync('output.pdf', pdf.data);
}

convertRepo('https://github.com/user/repo');

Support

For API support, contact us at support@mods-software.com or visit our FAQ.