Skip to content

api-reference.md

Latest commit

 

History

History
633 lines (504 loc) · 14.3 KB

api-reference.md

File metadata and controls

633 lines (504 loc) · 14.3 KB

API Reference

This document provides comprehensive documentation for all REST API endpoints provided by the DocSync plugin.

For workflows (non-authoritative examples), see the Sync Guide. For GitHub diagnostics/manual sync, see GitHub Sync Diagnostics.

Base URL

All endpoints use the base URL: /wp-json/docsync/v1/

Authentication

Public endpoints do not require authentication. Write/admin endpoints require WordPress authentication (cookies, application passwords, or other WP-authenticated mechanisms).

Documentation Endpoints

Permissions summary:

  • GET /docs and GET /docs/{id}: public
  • POST /docs and PUT /docs/{id}: edit_posts
  • DELETE /docs/{id}: delete_posts

GET /docs

List documentation posts.

Permissions: Public.

Query parameters:

  • per_page (int, default 10)
  • page (int, default 1)
  • project (string): Project term slug or numeric term ID
  • status (string, default publish)
  • search (string)

Response:

{
  "items": [
    {
      "id": 123,
      "title": "Getting Started",
      "slug": "getting-started",
      "excerpt": "Brief description",
      "status": "publish",
      "link": "https://example.com/docs/.../getting-started/",
      "project": {
        "assigned_term": {"id": 15, "slug": "my-plugin", "name": "My Plugin"},
        "project": {"id": 15, "slug": "my-plugin", "name": "My Plugin"},
        "category": {"id": 5, "slug": "wordpress-plugins", "name": "WordPress Plugins"},
        "project_type": "",
        "hierarchy_path": "wordpress-plugins/my-plugin"
      },
      "meta": {
        "sync_source_file": "README.md",
        "sync_hash": "...",
        "sync_timestamp": "2026-01-11T00:00:00Z"
      }
    }
  ],
  "total": 25,
  "pages": 3,
  "current_page": 1
}

content is not included in list responses. Use GET /docs/{id} for content.

POST /docs

Create a new documentation post.

Permissions: Requires edit_posts. Parameters:

  • title (string, required): Documentation title
  • content (string, required): Documentation content (supports Markdown)
  • excerpt (string): Brief description
  • status (string): Post status (default: "publish")
  • project_path (array): Taxonomy path as array (e.g., ["wordpress-plugins", "my-plugin"])
  • meta (object): Additional metadata

Response:

{
  "id": 124,
  "title": "New Documentation",
  "status": "publish",
  "project": {
    "assigned_term": {
      "id": 15,
      "slug": "my-plugin",
      "name": "My Plugin"
    },
    "project": {
      "id": 15,
      "slug": "my-plugin",
      "name": "My Plugin"
    },
    "category": {
      "id": 5,
      "slug": "wordpress-plugins",
      "name": "WordPress Plugins"
    },
    "project_type": "wordpress-plugin",
    "hierarchy_path": "wordpress-plugins/my-plugin"
  }
}

GET /docs/{id}

Get a specific documentation post.

Parameters:

  • id (int, required): Post ID

Response: Single documentation object. Same fields as list items, plus content (string) is included.

PUT /docs/{id}

Update an existing documentation post.

Permissions: Requires edit_posts. Parameters: Same as POST /docs, all optional except id.

Response: Updated documentation object.

DELETE /docs/{id}

Delete a documentation post.

Permissions: Requires delete_posts.

Parameters:

  • force (boolean, default false): Permanently delete instead of moving to trash

Response:

{
  "success": true,
  "id": 123,
  "deleted": false,
  "trashed": true
}

Project Taxonomy Endpoints

Permissions summary:

  • GET /project, GET /project/tree, GET /project/{id}: public
  • POST /project/resolve: public when create_missing=false, otherwise manage_categories
  • PUT /project/{id}: manage_categories

GET /project

List project taxonomy terms.

Permissions: Public.

Query parameters:

  • parent (int, default 0)
  • hide_empty (boolean, default false)

Response: Unwrapped array of term objects.

[
  {
    "id": 5,
    "name": "WordPress Plugins",
    "slug": "wordpress-plugins",
    "description": "",
    "parent": 0,
    "count": 15,
    "project_type": "",
    "is_top_level": true,
    "is_project": false
  }
]

GET /project/tree

Get the complete hierarchical project tree.

Permissions: Public.

Response: Array of nested term objects.

[
  {
    "id": 5,
    "name": "WordPress Plugins",
    "slug": "wordpress-plugins",
    "description": "",
    "parent": 0,
    "count": 15,
    "project_type": "",
    "is_top_level": true,
    "is_project": false,
    "children": [
      {
        "id": 12,
        "name": "My Plugin",
        "slug": "my-plugin",
        "description": "",
        "parent": 5,
        "count": 3,
        "project_type": "",
        "is_top_level": false,
        "is_project": true
      }
    ]
  }
]

POST /project/resolve

Resolve a taxonomy path to terms, optionally creating missing terms.

Permissions:

  • Public when create_missing is false
  • Requires manage_categories when create_missing is true

Body parameters:

  • path (array of strings, required): e.g. ["wordpress-plugins", "my-plugin", "api"]
  • create_missing (boolean, default false)
  • project_meta (object, default {}): applied during resolution (when creating/ensuring the project term)

Response:

{
  "success": true,
  "leaf_term_id": 15,
  "leaf_term_slug": "api",
  "path": "wordpress-plugins/my-plugin/api",
  "created": ["api"],
  "terms": [
    {"id": 5, "slug": "wordpress-plugins", "name": "WordPress Plugins"},
    {"id": 12, "slug": "my-plugin", "name": "My Plugin"},
    {"id": 15, "slug": "api", "name": "API"}
  ]
}

GET /project/{id}

Get a specific taxonomy term.

Parameters:

  • id (int, required): Term ID

Response: Single term object as shown in GET /project.

PUT /project/{id}

Update a taxonomy term.

Permissions: Requires manage_categories.

Body parameters:

  • name (string, optional)
  • description (string, optional)
  • meta (object, optional): only these keys are applied:
    • github_url (stored as term meta project_github_url)
    • wp_url (stored as term meta project_wp_url)

Response: Updated term object (includes meta and repository_info).

Sync Endpoints

Permissions summary:

  • POST /sync/setup: manage_categories
  • GET /sync/status: edit_posts
  • POST /sync/doc, POST /sync/batch: edit_posts
  • Manual GitHub sync and diagnostics (/sync/all, /sync/term/{id}, /sync/test-token, /sync/test-repo): manage_options

POST /sync/all

Manually sync all projects that have a GitHub URL configured.

Permissions: Requires manage_options.

Response:

{
  "repos_synced": 2,
  "total_added": 10,
  "total_updated": 3,
  "total_removed": 1,
  "errors": [],
  "message": "Synced 2 repos. Added: 10, Updated: 3, Removed: 1"
}

POST /sync/term/{id}

Manually sync a single project term.

Permissions: Requires manage_options.

Parameters:

  • id (int, required): Project term ID
  • force (boolean, default false)

Response:

{
  "added": 3,
  "updated": 1,
  "removed": 0,
  "message": "Added: 3, Updated: 1, Removed: 0"
}

GET /sync/test-token

Run GitHub token diagnostics using the configured PAT.

Permissions: Requires manage_options.

Response: Diagnostic object returned by the GitHub client.

POST /sync/test-repo

Test access to a specific GitHub repository.

Permissions: Requires manage_options.

Body parameters:

  • repo_url (string, required)

Response: Repository diagnostic object on success. On failure, returns a WP REST error; error data may include owner, repo, and sso_url.

POST /sync/setup

Setup a project and its category taxonomy terms.

Permissions: Requires manage_categories. Parameters:

  • project_slug (string, required): Project slug
  • project_name (string, required): Project display name
  • category_slug (string, required): Category slug (e.g., "wordpress-plugins")
  • category_name (string, required): Category display name

Response:

{
  "success": true,
  "category_term_id": 5,
  "category_slug": "wordpress-plugins",
  "project_term_id": 16,
  "project_slug": "my-project"
}

GET /sync/status

Get sync status for a specific project.

Permissions: Requires edit_posts.

Query parameters:

  • project (string, required): project term slug

Response:

{
  "total_docs": 15,
  "synced_docs": 15,
  "project_slug": "my-plugin",
  "project_term": 15,
  "docs": [
    {
      "post_id": 125,
      "title": "Getting Started",
      "source_file": "docs/README.md",
      "sync_filesize": "1024",
      "sync_timestamp": "2025-12-01T10:00:00Z",
      "status": "synced"
    }
  ]
}

POST /sync/doc

Sync a single documentation post from external sources.

Permissions: Requires edit_posts. Parameters:

  • source_file (string, required): Original source file path
  • title (string, required): Documentation title
  • content (string, required): Markdown content
  • project_term_id (int, required): Project taxonomy term ID
  • filesize (int, required): Size of source file in bytes
  • timestamp (string, required): ISO 8601 timestamp of last modification
  • subpath (array): Hierarchical path within project as array
  • excerpt (string): Brief description
  • force (boolean): Override existing content (default: false)

Response:

{
  "success": true,
  "post_id": 125,
  "action": "created",
  "term_id": 20,
  "term_path": "wordpress-plugins/my-plugin/api"
}

POST /sync/batch

Batch sync multiple documentation posts.

Permissions: Requires edit_posts. Parameters:

  • docs (array, required): Array of document objects (same structure as POST /sync/doc)

Response:

{
  "total": 5,
  "created": 3,
  "updated": 2,
  "unchanged": 0,
  "failed": 0,
  "results": [
    {
      "success": true,
      "post_id": 125,
      "action": "created"
    }
  ]
}

Error Responses

All endpoints return standard HTTP status codes:

  • 200: Success
  • 201: Created
  • 400: Bad Request (invalid parameters)
  • 401: Unauthorized
  • 403: Forbidden (insufficient permissions)
  • 404: Not Found
  • 500: Internal Server Error

Error response format:

This plugin uses WordPress REST error responses (see WP REST API). Shapes vary by error; for errors explicitly thrown by this plugin you typically receive:

{
  "code": "not_found",
  "message": "Documentation not found",
  "data": {
    "status": 404
  }
}

WP-CLI Commands

The plugin provides three WP-CLI commands for managing documentation and projects from the command line.

chubes project ensure

Ensures a project taxonomy term exists, creating it if necessary.

wp chubes project ensure <project-slug> [--name=<display-name>] [--github_url=<url>] [--wp_url=<url>]

Arguments:

  • project-slug (required): The project term slug

Options:

  • --name: Display name for the project (defaults to slug)
  • --github_url: GitHub repository URL
  • --wp_url: WordPress.org plugin/theme URL

Example:

wp chubes project ensure my-plugin --name="My Plugin" --github_url="https://github.com/username/my-plugin"

chubes project tree

Displays the project taxonomy as a tree structure.

wp chubes project tree [--parent=<term-id>] [--depth=<depth>]

Options:

  • --parent: Term ID to start from (default: 0 for top-level)
  • --depth: Maximum depth to display (default: 3)

Example:

wp chubes project tree
wp chubes project tree --depth=5

chubes docs sync

Manually trigger documentation sync from GitHub.

wp chubes docs sync [term-id] [--all] [--force]

Arguments:

  • term-id: Specific project term ID to sync (optional)

Options:

  • --all: Sync all projects with GitHub URLs
  • --force: Force re-sync even when content hasn't changed

Example:

# Sync a specific project
wp chubes docs sync 15

# Sync all projects
wp chubes docs sync --all

# Force sync all projects
wp chubes docs sync --all --force

Abilities (AI Agent Integration)

The plugin registers Abilities for AI agents (WP Abilities API). These enable AI assistants to interact with documentation programmatically.

chubes/get-doc

Fetch a single documentation post by ID or slug.

Input:

  • id (integer): Post ID
  • slug (string): Post slug (alternative to id)
  • format (string): Content format - "markdown" (default) or "html"

Output:

{
  "id": 123,
  "title": "Getting Started",
  "content": "# Getting Started\n\n...",
  "content_format": "markdown",
  "excerpt": "Brief description",
  "link": "https://example.com/docs/.../",
  "project": {
    "id": 15,
    "name": "My Plugin",
    "slug": "my-plugin"
  },
  "project_type": {
    "id": 5,
    "name": "WordPress Plugin",
    "slug": "wordpress-plugin"
  },
  "meta": {
    "sync_source_file": "docs/README.md",
    "sync_hash": "abc123",
    "sync_timestamp": "2026-01-15T10:00:00Z"
  }
}

chubes/search-docs

Search published documentation by query string, optionally filtered by project.

Input:

  • query (string, required): Search query string
  • project (integer): Project term ID to filter results
  • per_page (integer): Number of results (max 50, default 10)

Output:

{
  "items": [
    {
      "id": 123,
      "title": "Getting Started",
      "excerpt": "Brief description...",
      "link": "https://example.com/docs/.../",
      "project": {
        "id": 15,
        "name": "My Plugin",
        "slug": "my-plugin"
      }
    }
  ],
  "total": 5,
  "query": "getting started"
}

chubes/sync-docs

Sync documentation from GitHub. Requires GitHub PAT to be configured.

Input:

  • term_id (integer): Sync a specific project (optional)
  • term_ids (array): Sync multiple projects (optional)

Output:

{
  "success": true,
  "repos_synced": 2,
  "total_added": 10,
  "total_updated": 3,
  "total_removed": 1,
  "added": ["docs/api.md", "docs/usage.md"],
  "updated": ["docs/README.md"],
  "removed": ["docs/old.md"],
  "errors": []
}

chubes/reset-documentation

Delete all documentation posts and child terms, preserving top-level projects with GitHub URLs.

Input: None required

Output:

{
  "success": true,
  "documentation_posts_deleted": 25,
  "child_terms_deleted": 15,
  "orphaned_terms_deleted": 2,
  "sync_metadata_reset": 10
}