> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docswrite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create WordPress Post

> Create or update WordPress posts and pages from Google Docs

## Additional Information

### Best Practices

1. **Always share Google Docs** with "Anyone with the link"
2. **Test with drafts first** before publishing live content
3. **Use descriptive titles and slugs** for better SEO
4. **Include alt text for images** for accessibility
5. **Set appropriate categories and tags** to organize content

## Create WordPress Post

Create or update a blog post or page on your WordPress site from a Google Docs document.

```bash theme={null}
POST https://api.docswrite.com/api/export?token=YOUR_TOKEN
```

### Headers

| Header       | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

### Request Body

The request body should contain the Google Docs URL and any additional parameters to customize the post.

### Required Parameters

| Parameter         | Type   | Description                                                       |
| ----------------- | ------ | ----------------------------------------------------------------- |
| `google_docs_url` | string | URL of the Google Doc. **Must be shared with "anyone with link"** |

### Optional Parameters

| Parameter                 | Type   | Default           | Description                                  |
| ------------------------- | ------ | ----------------- | -------------------------------------------- |
| `title`                   | string | Google Docs title | Post title                                   |
| `slug`                    | string | Auto-generated    | Custom URL slug                              |
| `tags`                    | string | -                 | Comma-separated list of tags                 |
| `categories`              | string | -                 | Comma-separated list of categories           |
| `state`                   | string | `draft`           | Post status: `publish` or `draft`            |
| `author`                  | string | API token creator | Author username or full name                 |
| `date`                    | string | Current time      | Publish date in `YYYY-MM-DD HH:MM:SS` format |
| `excerpt`                 | string | -                 | Post excerpt for SEO                         |
| `post_type`               | string | `post`            | Type: `post` or `page`                       |
| `featured_image_url`      | string | -                 | URL of featured image                        |
| `featured_image_alt_text` | string | -                 | Alt text for featured image                  |
| `featured_image_caption`  | string | -                 | Caption for featured image                   |

### Export Settings

Control how your content is processed:

| Parameter                                         | Type    | Default   | Description                                     |
| ------------------------------------------------- | ------- | --------- | ----------------------------------------------- |
| `export_settings.compress_images`                 | boolean | `true`    | Compress images before upload                   |
| `export_settings.demote_headings`                 | boolean | `false`   | Demote headings by one level                    |
| `export_settings.convert_to_webp`                 | boolean | `true`    | Convert images to WebP format                   |
| `export_settings.first_image_as_featured_image`   | boolean | `true`    | Set first image as featured image               |
| `export_settings.add_no_follow_to_external_links` | boolean | `true`    | Add `nofollow` to external links                |
| `export_settings.bold_as_strong`                  | boolean | `false`   | Convert bold text to `strong` tag               |
| `export_settings.wp_content_editor`               | string  | `classic` | Content editor: `classic` or `gutenberg_editor` |

### SEO Plugin Settings

#### Yoast SEO Settings

| Parameter                        | Type   | Description      |
| -------------------------------- | ------ | ---------------- |
| `yoast_settings.yoast_focuskw`   | string | Focus keyword    |
| `yoast_settings.yoast_metadesc`  | string | Meta description |
| `yoast_settings.yoast_title`     | string | SEO title        |
| `yoast_settings.yoast_canonical` | string | Canonical URL    |

#### RankMath Settings

| Parameter                                   | Type   | Description   |
| ------------------------------------------- | ------ | ------------- |
| `rankmath_settings.rank_math_focus_keyword` | string | Focus keyword |

#### Newspack Settings

| Parameter                                          | Type   | Description     |
| -------------------------------------------------- | ------ | --------------- |
| `newspack_settings.newspack_article_summary`       | string | Article summary |
| `newspack_settings.newspack_article_summary_title` | string | Summary title   |
| `newspack_settings.newspack_post_subtitle`         | string | Post subtitle   |

### Advanced Custom Fields (ACF)

| Parameter        | Type   | Description                                   |
| ---------------- | ------ | --------------------------------------------- |
| `acf_field_name` | string | Custom field value (supports URLs for images) |

## Example Requests

### Basic Request

```json theme={null}
{
  "google_docs_url": "https://docs.google.com/document/d/1aBcDeFg/edit?usp=sharing",
  "title": "My Blog Post",
  "state": "publish",
  "categories": "Technology, WordPress",
  "tags": "automation, publishing"
}
```

### Complete Request with All Options

```json theme={null}
{
  "google_docs_url": "https://docs.google.com/document/d/1aBcDeFgHiJkLmNopQrStUvWxYz/edit?usp=sharing",
  "title": "Complete Example Blog Post",
  "slug": "complete-example-blog-post",
  "tags": "example, blog post, complete",
  "categories": "Technology, Tutorials",
  "state": "draft",
  "author": "Jane Doe",
  "date": "2024-04-01 09:00:00",
  "excerpt": "This is a comprehensive example of all available parameters.",
  "post_type": "post",
  "featured_image_url": "https://images.unsplash.com/photo-1662572091420-95992f339784",
  "featured_image_alt_text": "Complete Example Featured Image",
  "featured_image_caption": "Example caption for the featured image",
  "export_settings": {
    "compress_images": true,
    "demote_headings": false,
    "convert_to_webp": true,
    "first_image_as_featured_image": true,
    "add_no_follow_to_external_links": true,
    "bold_as_strong": false,
    "wp_content_editor": "classic"
  },
  "newspack_settings": {
    "newspack_article_summary": "This is an example article summary for Newspack themes.",
    "newspack_article_summary_title": "Example Summary Title",
    "newspack_post_subtitle": "Example Post Subtitle"
  },
  "yoast_settings": {
    "yoast_focuskw": "example blog post",
    "yoast_metadesc": "This is a comprehensive example meta description for SEO.",
    "yoast_title": "Complete Example Blog Post | My Site"
  },
  "rankmath_settings": {
    "rank_math_focus_keyword": "example blog post"
  }
}
```

### Scheduled Post Request

```json theme={null}
{
  "google_docs_url": "https://docs.google.com/document/d/1aBcDeFg/edit",
  "title": "Scheduled Blog Post",
  "state": "publish",
  "date": "2024-12-25 10:00:00",
  "categories": "Holiday, Special"
}
```

## Response Examples

### Success Response (200 OK)

```json theme={null}
{
  "error": false,
  "message": "Post added to queue",
  "data": {
    "google_docs_url": "https://docs.google.com/document/d/1aBcDeFg/edit",
    "title": "My Blog Post",
    "jobId": "job-abc123"
  }
}
```

### Error Responses

**Bad Request (400)**

```json theme={null}
{
  "error": true,
  "message": "Invalid Google Docs URL",
  "details": "The provided URL is not accessible or not shared properly"
}
```

**Unauthorized (401)**

```json theme={null}
{
  "error": true,
  "message": "Invalid API token",
  "details": "Please check your API token and try again"
}
```

**Rate Limited (429)**

```json theme={null}
{
  "error": true,
  "message": "Rate limit exceeded",
  "details": "You've exceeded the rate limit. Please wait before making more requests."
}
```

## cURL Examples

### Basic cURL Request

```bash theme={null}
curl -X POST 'https://api.docswrite.com/api/export?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "google_docs_url": "https://docs.google.com/document/d/1aBcDeFg/edit",
    "title": "My Blog Post",
    "state": "publish",
    "categories": "Technology, WordPress",
    "tags": "automation, publishing"
  }'
```

### Advanced cURL Request with SEO

```bash theme={null}
curl -X POST 'https://api.docswrite.com/api/export?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "google_docs_url": "https://docs.google.com/document/d/1aBcDeFg/edit",
    "title": "SEO Optimized Post",
    "state": "publish",
    "yoast_settings": {
      "yoast_focuskw": "SEO optimization",
      "yoast_metadesc": "Learn how to optimize your content for search engines"
    },
    "export_settings": {
      "compress_images": true,
      "convert_to_webp": true
    }
  }'
```


## OpenAPI

````yaml POST /api/export
openapi: 3.1.0
info:
  title: Docswrite API
  description: REST API for publishing Google Docs to WordPress with Docswrite
  version: 1.0.0
  contact:
    name: Docswrite Support
    url: >-
      https://join.slack.com/t/docswritecom/shared_invite/zt-1j0f1wly8-8lEYgDLDGfBFRkh50SRF7Q
    email: support@docswrite.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.docswrite.com
    description: Production server
security:
  - apiToken: []
paths:
  /api/export:
    post:
      summary: Create WordPress Post
      description: Create or update a WordPress post/page from a Google Docs document
      parameters:
        - name: token
          in: query
          required: true
          description: Your personal API token
          schema:
            type: string
      requestBody:
        description: Post creation parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostRequest'
        required: true
      responses:
        '200':
          description: Post creation initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePostResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CreatePostRequest:
      type: object
      required:
        - google_docs_url
      properties:
        google_docs_url:
          type: string
          format: uri
          description: URL of the Google Doc (must be shared with 'anyone with link')
          example: https://docs.google.com/document/d/1aBcDeFg/edit
        title:
          type: string
          description: Post title (defaults to Google Docs title)
          example: My Blog Post
        slug:
          type: string
          description: Custom URL slug (auto-generated if not provided)
          example: my-blog-post
        tags:
          type: string
          description: Comma-separated list of tags
          example: technology, wordpress, automation
        categories:
          type: string
          description: Comma-separated list of categories
          example: Technology, Tutorials
        state:
          type: string
          enum:
            - draft
            - publish
          default: draft
          description: Post publication status
        author:
          type: string
          description: Author username or full name
          example: John Doe
        date:
          type: string
          format: date-time
          description: Publication date in YYYY-MM-DD HH:MM:SS format
          example: '2024-04-01 09:00:00'
        excerpt:
          type: string
          description: Post excerpt for SEO
          example: This is a brief description of the post content.
        post_type:
          type: string
          enum:
            - post
            - page
          default: post
          description: Type of content to create
        featured_image_url:
          type: string
          format: uri
          description: URL of the featured image
          example: https://example.com/image.jpg
        featured_image_alt_text:
          type: string
          description: Alt text for the featured image
          example: Description of the featured image
        featured_image_caption:
          type: string
          description: Caption for the featured image
          example: Image caption text
        export_settings:
          $ref: '#/components/schemas/ExportSettings'
        yoast_settings:
          $ref: '#/components/schemas/YoastSettings'
        rankmath_settings:
          $ref: '#/components/schemas/RankMathSettings'
        newspack_settings:
          $ref: '#/components/schemas/NewspackSettings'
    CreatePostResponse:
      type: object
      properties:
        error:
          type: boolean
          example: false
        message:
          type: string
          example: Post added to queue
        data:
          type: object
          properties:
            google_docs_url:
              type: string
              example: https://docs.google.com/document/d/1aBcDeFg/edit
            title:
              type: string
              example: My Blog Post
            jobId:
              type: string
              example: job-abc123
    ErrorResponse:
      type: object
      properties:
        error:
          type: boolean
          example: true
        message:
          type: string
          example: Invalid Google Docs URL
        details:
          type: string
          example: The provided URL is not accessible or not shared properly
    ExportSettings:
      type: object
      properties:
        compress_images:
          type: boolean
          default: true
          description: Compress images before upload
        demote_headings:
          type: boolean
          default: false
          description: Demote headings by one level
        convert_to_webp:
          type: boolean
          default: true
          description: Convert images to WebP format
        first_image_as_featured_image:
          type: boolean
          default: true
          description: Set the first image as featured image
        add_no_follow_to_external_links:
          type: boolean
          default: true
          description: Add nofollow attribute to external links
        bold_as_strong:
          type: boolean
          default: false
          description: Convert bold text to strong tag
        wp_content_editor:
          type: string
          enum:
            - classic
            - gutenberg_editor
          default: classic
          description: WordPress content editor to use
    YoastSettings:
      type: object
      properties:
        yoast_focuskw:
          type: string
          description: Yoast focus keyword
          example: wordpress automation
        yoast_metadesc:
          type: string
          description: Yoast meta description
          example: Learn how to automate WordPress publishing with Docswrite
        yoast_title:
          type: string
          description: Yoast SEO title
          example: WordPress Automation Guide | My Site
        yoast_canonical:
          type: string
          format: uri
          description: Canonical URL
          example: https://example.com/wordpress-automation
    RankMathSettings:
      type: object
      properties:
        rank_math_focus_keyword:
          type: string
          description: RankMath focus keyword
          example: wordpress automation
    NewspackSettings:
      type: object
      properties:
        newspack_article_summary:
          type: string
          description: Article summary for Newspack
          example: This article covers WordPress automation techniques
        newspack_article_summary_title:
          type: string
          description: Article summary title for Newspack
          example: WordPress Automation Summary
        newspack_post_subtitle:
          type: string
          description: Post subtitle for Newspack
          example: A comprehensive guide to automation
  securitySchemes:
    apiToken:
      type: apiKey
      in: query
      name: token
      description: API token obtained from Docswrite dashboard

````