Post API

The Post API is the core public capability of the GeoWriter Integration API. It covers the full article generation and publishing flow.

1. Create a document
2. Check generation progress
3. Get document details
4. List available publish configs
5. Get taxonomy for a target blog
6. Submit a publish task
7. Check publish progress

Authentication

• Header: Authorization: Bearer <API_KEY>
• API key format: sk-gw-...
• Recommended scopes:
  • documents:write for document creation
  • documents:read for progress and detail queries

Response Format

Success:

{
  "success": true,
  "data": {},
  "message": ""
}

Error example:

{
  "success": false,
  "data": null,
  "message": "Invalid API key."
}

1. Create Document

POST /api/v1/documents/create

Parameters:

• keyword: required, target keyword.
• language: optional, defaults to en.
• country: optional, defaults to united-states.
• need_image: optional, defaults to true.
• idempotency_key: optional. Generated automatically if omitted.

{
  "keyword": "best hiking trails"
}

{
  "document_id": "123"
}

2. Get Generation Progress

GET /api/v1/documents/progress/{id}

{
  "stage": 3,
  "stage_name": "Generating outline",
  "progress": 65,
  "status": "GENERATING",
  "completed": false
}

3. Get Document Detail

GET /api/v1/documents/detail/{id}

{
  "id": "123",
  "keyword": "best hiking trails",
  "title": "Best Hiking Trails",
  "meta_description": "...",
  "body": "...",
  "status": "DRAFT",
  "created_at": "2026-03-11T10:00:00Z",
  "updated_at": "2026-03-11T10:05:00Z"
}

4. Publishing Prerequisites

Before submitting a publish task, fetch the publish config list and the taxonomy for the selected blog.

4.1 List Publish Configs

GET /api/v1/publish-configs/list

Requires publish:read.

{
  "configs": [
    {
      "id": 12,
      "name": "Main Blog",
      "platform": "wordpress",
      "status": "active",
      "site_url": "https://blog.example.com",
      "settings": {
        "default_status": "draft"
      }
    }
  ]
}

4.2 Get Blog Taxonomy

GET /api/v1/publish-configs/taxonomy/{id}

Requires publish:read. Categories are returned as a tree under children, and tags are returned as a flat list.

{
  "publish_config": {
    "id": 12,
    "name": "Main Blog",
    "platform": "wordpress",
    "status": "active",
    "site_url": "https://blog.example.com"
  },
  "categories": [
    {
      "id": 10,
      "name": "Travel",
      "slug": "travel",
      "parent": 0,
      "count": 8,
      "children": [
        {
          "id": 11,
          "name": "Asia",
          "slug": "asia",
          "parent": 10,
          "count": 3,
          "children": []
        }
      ]
    }
  ],
  "tags": [
    {
      "id": 100,
      "name": "SEO",
      "slug": "seo",
      "count": 12
    }
  ],
  "category_count": 2,
  "tag_count": 1
}

5. Submit Publish Task

POST /api/v1/documents/publish/submit/{id}

Requires publish:write.

Parameters:

• publish_config_id: required, target publish config ID.
• options.status: optional, supports draft or publish. Defaults to publish_config.settings.default_status, or draft if not configured.
• options.categories: optional array of category IDs.
• options.tags: optional array of tag IDs.
• options.remove_featured_from_content: optional boolean.

For updates, the target platform keeps its existing post status.

{
  "publish_config_id": 12,
  "options": {
    "status": "draft"
  }
}

{
  "document_id": "123"
}

6. Get Publish Progress

GET /api/v1/documents/publish/progress/{id}

Requires publish:read. Poll every 10 seconds if needed.

{
  "status": "completed",
  "progress": 100,
  "completed": true,
  "published_url": "https://blog.example.com/best-hiking-trails/",
  "error_message": null
}

Recommended Path

If you do not want to manage the workflow yourself, use the official AIWriter Skill.