# Google Doc Maker API

Convert Markdown to formatted Google Docs via a simple REST API.

**$0.01 per document. You only pay when the doc is created successfully.**

Base URL: `https://api.googledocmaker.com`

## How It Works

You send Markdown content. We create a real Google Doc in the user's Google Drive with proper formatting: headings, bold, italic, tables, lists, links, code blocks. The doc is a native Google Doc (not a PDF, not an import), fully editable and shareable.

Two operations:

- **Create** - Make a new Google Doc from Markdown. Optionally clone a template doc first for branding (logo, fonts, headers/footers). Optionally set sharing permissions.
- **Append** - Add more Markdown content to an existing Google Doc. Useful for building docs incrementally.

Each user connects their own Google account via OAuth. Documents are created in their Google Drive.

## Quick Start

### 1. Create an account

```bash
curl -X POST https://api.googledocmaker.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'
```

You'll get a 6-digit verification code in your email.

### 2. Verify your email

```bash
curl -X POST https://api.googledocmaker.com/api/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "123456"}'
```

### 3. Get your API key

```bash
curl -X POST https://api.googledocmaker.com/api/v1/auth/api-key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'
```

Response:

```json
{
  "api_key": "gd_live_kuE9UyksbOpJq0EGBElHxBVuqe4SHkg8tfvnK6r8ML4",
  "key_prefix": "gd_live_kuE9",
  "credits_balance": 5,
  "message": "Save this key. It will not be shown again."
}
```

Save this key. It is only shown once. You start with 5 free credits.

### 4. Connect your Google account (one-time setup)

Open this URL in a browser with your API key as a header or query parameter:

```
GET https://api.googledocmaker.com/api/v1/google/connect
Header: X-API-Key: gd_live_YOUR_KEY
```

This redirects you to Google's consent screen. Sign in and authorize the app to create documents on your behalf. Your refresh token is encrypted with Fernet and stored securely. You only need to do this once.

Check connection status:

```bash
curl https://api.googledocmaker.com/api/v1/google/status \
  -H "X-API-Key: gd_live_YOUR_KEY"
```

```json
{
  "connected": true,
  "scopes": [
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/drive"
  ]
}
```

### 5. Create a Google Doc

```bash
curl -X POST https://api.googledocmaker.com/api/v1/docs/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gd_live_YOUR_KEY" \
  -d '{
    "title": "Q1 Sales Report",
    "markdown_content": "# Q1 Results\n\n**Revenue**: $2.4M (+18% YoY)\n\n## Regional Breakdown\n\n| Region | Deals Closed | Revenue |\n|--------|-------------|----------|\n| West   | 23          | $1.2M    |\n| East   | 24          | $1.2M    |\n\n## Next Steps\n\n- Expand to Midwest territory\n- Hire 2 additional sales reps\n- Launch Q2 campaign by April 1",
    "sharing": "anyone_with_link"
  }'
```

Response:

```json
{
  "doc_id": "1lx5OB-XeY4XCcRoelxoxj7aW-bKWoPUuUR2f5ZG7Za8",
  "url": "https://docs.google.com/document/d/1lx5OB-XeY4XCcRoelxoxj7aW-bKWoPUuUR2f5ZG7Za8/edit",
  "title": "Q1 Sales Report",
  "credits_charged": 1,
  "credits_remaining": 4
}
```

The `url` field links directly to the editable Google Doc.

### 6. Append to an existing doc

```bash
curl -X POST https://api.googledocmaker.com/api/v1/docs/append \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gd_live_YOUR_KEY" \
  -d '{
    "doc_id": "1lx5OB-XeY4XCcRoelxoxj7aW-bKWoPUuUR2f5ZG7Za8",
    "markdown_content": "## Q2 Update\n\nAdded 12 new accounts in March. Pipeline at $3.1M."
  }'
```

## Request/Response Reference

### POST /api/v1/docs/create

Create a new Google Doc from Markdown content.

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | Yes | Title of the Google Doc |
| `markdown_content` | string | Yes | Markdown content to render |
| `template_id` | string | No | Google Doc ID to clone as template (preserves formatting, headers, footers, logo) |
| `folder_id` | string | No | Google Drive folder ID to create the doc in |
| `sharing` | string | No | Sharing permission: `"private"` (default), `"anyone_with_link"`, or `"public"` |

**Response (201):**

| Field | Type | Description |
|-------|------|-------------|
| `doc_id` | string | Google Doc ID |
| `url` | string | Direct edit URL |
| `title` | string | Document title |
| `credits_charged` | integer | Credits used (1 for regular users, 0 for admin) |
| `credits_remaining` | integer | Remaining credit balance |

### POST /api/v1/docs/append

Append Markdown content to an existing Google Doc.

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `doc_id` | string | Yes | Google Doc ID to append to |
| `markdown_content` | string | Yes | Markdown content to append |

**Response (200):** Same as create response.

### GET /api/v1/google/connect

Redirects to Google OAuth consent screen. Requires `X-API-Key` header. After authorization, the user's refresh token is encrypted and stored. Redirects to success page on completion.

### GET /api/v1/google/status

Check if the user's Google account is connected.

**Response (200):**

```json
{
  "connected": true,
  "scopes": ["https://www.googleapis.com/auth/documents", "https://www.googleapis.com/auth/drive"]
}
```

### POST /api/v1/auth/register

Register a new account.

**Request body:** `{"email": "user@example.com"}`

**Response (200):** `{"message": "If this email is eligible, a verification code has been sent.", "email": "user@example.com"}`

### POST /api/v1/auth/verify

Verify email with 6-digit code.

**Request body:** `{"email": "user@example.com", "code": "123456"}`

**Response (200):** `{"message": "Email verified. You can now generate an API key.", "email": "user@example.com", "verified": true}`

### POST /api/v1/auth/api-key

Generate an API key. Email must be verified first.

**Request body:** `{"email": "user@example.com"}`

**Response (201):**

```json
{
  "api_key": "gd_live_...",
  "key_prefix": "gd_live_xxxx",
  "credits_balance": 5,
  "message": "Save this key. It will not be shown again."
}
```

### GET /api/v1/account

View account details and recent usage.

**Response (200):**

```json
{
  "email": "user@example.com",
  "credits_balance": 4,
  "total_queries": 1,
  "total_charged": 1,
  "key_prefix": "gd_live_xxxx",
  "is_active": true,
  "recent_usage": [
    {
      "endpoint": "/docs/create",
      "request_params": {"title": "Q1 Report"},
      "credits_charged": 1,
      "refunded": false,
      "created_at": "2026-03-20T05:08:37.890000"
    }
  ]
}
```

### GET /api/v1/credits/packs

List available credit packs with Stripe pricing.

### POST /api/v1/credits/purchase

Buy credits via Stripe Checkout.

**Request body:** `{"pack_id": "pack_100"}`

**Response:** Stripe Checkout session URL.

## Supported Markdown Elements

The following Markdown elements are converted to native Google Docs formatting:

| Element | Markdown Syntax | Google Docs Result |
|---------|----------------|-------------------|
| Heading 1 | `# Title` | Title style heading |
| Heading 2 | `## Section` | Heading 2 style |
| Heading 3-6 | `### ...` | Heading 3-6 styles |
| Bold | `**text**` | Bold text |
| Italic | `*text*` | Italic text |
| Strikethrough | `~~text~~` | Strikethrough text |
| Link | `[text](url)` | Clickable hyperlink |
| Bullet list | `- item` | Bulleted list |
| Numbered list | `1. item` | Numbered list |
| Table | `\| A \| B \|` | Google Docs table |
| Code (inline) | `` `code` `` | Monospace font |
| Code block | ` ```code``` ` | Monospace paragraph |
| Horizontal rule | `---` | Section break |
| Blockquote | `> text` | Indented paragraph |

## Template Support

Pass a `template_id` to clone an existing Google Doc before inserting content. The template doc should be in the user's Google Drive. The API copies the template (preserving all formatting, headers, footers, logos, page setup) and then inserts the Markdown content into the copy.

```bash
curl -X POST https://api.googledocmaker.com/api/v1/docs/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gd_live_YOUR_KEY" \
  -d '{
    "title": "Client Proposal - Acme Corp",
    "markdown_content": "# Proposal for Acme Corp\n\n...",
    "template_id": "1abc...xyz"
  }'
```

## Sharing Permissions

The `sharing` parameter on `/docs/create` controls who can access the document:

| Value | Effect |
|-------|--------|
| `"private"` (default) | Only the Google account owner can access |
| `"anyone_with_link"` | Anyone with the URL can view |
| `"public"` | Discoverable and viewable by anyone |

## Error Handling

All errors return JSON with a `detail` field:

```json
{"detail": "Error description here"}
```

### Error Codes

| Code | Meaning | Action |
|------|---------|--------|
| 201 | Document created | Success |
| 200 | Success | Success |
| 400 | Bad request | Check request body format |
| 401 | Invalid API key or Google access revoked | Check key or reconnect Google at `/api/v1/google/connect` |
| 402 | Insufficient credits | Purchase more at `/api/v1/credits/purchase` |
| 403 | Google not connected | Connect at `/api/v1/google/connect` |
| 409 | Email already registered | Use existing account |
| 422 | Invalid Markdown | Check Markdown syntax |
| 429 | Rate limit exceeded | Wait and retry (check `Retry-After` header) |
| 500 | Internal encryption error | Contact support |
| 502 | Google Docs API error | Retry, check Google service status |

### Automatic Refunds

If document creation fails after credits are deducted (Google API error, token revocation, Markdown parse error), the credit is automatically refunded. You only pay for successful operations.

## Authentication

All document and account endpoints require an API key:

```
X-API-Key: gd_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ...
```

Keys are prefixed with `gd_live_` for identification. The key is hashed with SHA-256 before storage. If you lose your key, generate a new one via `/api/v1/auth/api-key`.

## Rate Limits

| Endpoint Group | Limit |
|---------------|-------|
| `/api/v1/docs/*` | 60 requests per minute per API key |
| `/api/v1/auth/*` | 10 requests per minute per IP |

When rate-limited, the API returns 429 with a `Retry-After` header.

## Pricing

| Pack | Credits | Price | Per Document |
|------|---------|-------|-------------|
| Free | 5 | $0.00 | On signup |
| 100 | 100 | $1.00 | $0.01 |
| 1,000 | 1,000 | $10.00 | $0.01 |
| 10,000 | 10,000 | $100.00 | $0.01 |

Credits never expire. Failed operations are automatically refunded.