# Google Doc Maker API

> Send Markdown content. Get back a formatted Google Doc with a shareable URL. $0.01 per document. You only pay when the doc is created successfully.

## Documentation

- [Full API Documentation](https://googledocmaker.com/llms-full.txt): Complete API reference with all endpoints, authentication, Google OAuth setup, pricing, error codes, and curl examples
- [OpenAPI Specification](https://googledocmaker.com/openapi.json): Machine-readable API schema for tool integration and code generation

## Quick Start

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

### 1. Register and get an API key

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

# Verify email (check inbox for 6-digit code)
curl -X POST https://api.googledocmaker.com/api/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "123456"}'

# Get API key (5 free credits included)
curl -X POST https://api.googledocmaker.com/api/v1/auth/api-key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'
```

### 2. Connect your Google account (one-time)

Open this URL in a browser (replace YOUR_KEY):

```
https://api.googledocmaker.com/api/v1/google/connect?api_key=gd_live_YOUR_KEY
```

Sign into Google and authorize. Your refresh token is encrypted and stored securely.

### 3. 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": "My Report",
    "markdown_content": "# Hello World\n\nThis is **bold** and this is a [link](https://example.com).\n\n| Col A | Col B |\n|-------|-------|\n| 1     | 2     |",
    "sharing": "anyone_with_link"
  }'
```

Response:

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

### 4. 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": "## New Section\n\nMore content added later."
  }'
```

## All Endpoints

### Documents

| Method | Endpoint | Auth | Cost | Description |
|--------|----------|------|------|-------------|
| POST | `/api/v1/docs/create` | X-API-Key | 1 credit | Create a Google Doc from Markdown |
| POST | `/api/v1/docs/append` | X-API-Key | 1 credit | Append Markdown to an existing doc |

### Google Account

| Method | Endpoint | Auth | Cost | Description |
|--------|----------|------|------|-------------|
| GET | `/api/v1/google/connect` | X-API-Key | Free | Start Google OAuth flow (browser redirect) |
| GET | `/api/v1/google/callback` | None | Free | OAuth callback (handled automatically) |
| GET | `/api/v1/google/status` | X-API-Key | Free | Check if Google account is connected |

### Authentication

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/api/v1/auth/register` | None | Create account (sends verification email) |
| POST | `/api/v1/auth/verify` | None | Verify email with 6-digit code |
| POST | `/api/v1/auth/api-key` | None | Generate API key (5 free credits) |

### Account & Credits

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/api/v1/account` | X-API-Key | View balance, usage, recent queries |
| DELETE | `/api/v1/account` | X-API-Key | Delete account |
| GET | `/api/v1/credits/packs` | None | List available credit packs |
| POST | `/api/v1/credits/purchase` | X-API-Key | Buy credits via Stripe Checkout |

### System

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/health` | None | Health check and service status |

## Pricing

- **$0.01 per document** created or appended to
- Failed creations are free (credit automatically refunded)
- 5 free credits on signup

### Credit Packs

| Pack | Credits | Price |
|------|---------|-------|
| 100 | 100 documents | $1.00 |
| 1,000 | 1,000 documents | $10.00 |
| 10,000 | 10,000 documents | $100.00 |

## Supported Markdown

- Headings (H1 through H6)
- Bold, italic, strikethrough
- Links (inline and reference)
- Bullet lists and numbered lists
- Tables (with headers)
- Code blocks (inline and fenced)
- Horizontal rules
- Blockquotes

## Authentication

All document endpoints require an API key passed as an HTTP header:

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

## Rate Limits

- 60 requests per minute per API key (document endpoints)
- 10 requests per minute (auth endpoints)

## Error Codes

| Code | Meaning |
|------|---------|
| 201 | Document created successfully |
| 200 | Success (append, status check) |
| 400 | Bad request (missing fields) |
| 401 | Missing or invalid API key, or Google access revoked |
| 402 | Insufficient credits |
| 403 | Google account not connected |
| 422 | Invalid or malformed Markdown |
| 429 | Rate limit exceeded |
| 500 | Internal error (encryption failure) |
| 502 | Google Docs API error |