API Reference

Last updated: March 1, 2026

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:

json

{
  "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

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

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

Create a new documentation post.

json

{
  "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}

Permissions: Requires edit_posts. Parameters:

Response:

id (int, required): Post ID

Get a specific documentation post.

PUT /docs/{id}

Parameters:

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

Update an existing documentation post.

DELETE /docs/{id}

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

Response: Updated documentation object.

Delete a documentation post.

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

Permissions: Requires delete_posts.

json

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

Project Taxonomy Endpoints

Parameters:

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

Response:

Permissions summary:

List project taxonomy terms.

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

Permissions: Public.

json

[
  {
    "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

Query parameters:

Response: Unwrapped array of term objects.

Get the complete hierarchical project tree.

json

[
  {
    "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

Permissions: Public.

Response: Array of nested term objects.

Public when create_missing is false
Requires manage_categories when create_missing is true

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

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)

Permissions:

json

{
  "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}

Body parameters:

Response:

id (int, required): Term ID

Get a specific taxonomy term.

PUT /project/{id}

Parameters:

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

Update a taxonomy term.

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)

Permissions: Requires manage_categories.

Sync Endpoints

Body parameters:

github_url (stored as term meta project_github_url)
wp_url (stored as term meta project_wp_url)

POST /sync/all

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

Permissions summary:

Manually sync all projects that have a GitHub URL configured.

json

{
  "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}

Permissions: Requires manage_options.

Response:

Manually sync a single project term.

github_url (stored as term meta project_github_url)
wp_url (stored as term meta project_wp_url)

Permissions: Requires manage_options.

json

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

GET /sync/test-token

Parameters:

Response:

Run GitHub token diagnostics using the configured PAT.

POST /sync/test-repo

Permissions: Requires manage_options.

Response: Diagnostic object returned by the GitHub client.

Test access to a specific GitHub repository.

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

Permissions: Requires manage_options.

POST /sync/setup

Body parameters:

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

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

Setup a project and its category taxonomy terms.

json

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

GET /sync/status

Permissions: Requires manage_categories. Parameters:

Response:

Get sync status for a specific project.

repo_url (string, required)

Permissions: Requires edit_posts.

json

{
  "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

Query parameters:

Response:

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

Sync a single documentation post from external sources.

json

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

POST /sync/batch

Permissions: Requires edit_posts. Parameters:

Response:

project (string, required): project term slug

Batch sync multiple documentation posts.

json

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

Error Responses

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:

All endpoints return standard HTTP status codes:

json

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

WP-CLI Commands

Error response format:

`chubes project ensure`

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:

bash

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

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

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

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

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

Arguments:

bash

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

`chubes project tree`

Options:

bash

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

Example:

project-slug (required): The project term slug

Displays the project taxonomy as a tree structure.

bash

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

`chubes docs sync`

Options:

bash

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

Example:

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

Manually trigger documentation sync from GitHub.

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

Arguments:

bash

# 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)

Options:

chubes/get-doc

Example:

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

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

Fetch a single documentation post by ID or slug.

json

{
  "id": 123,
  "title": "Getting Started",
  "content": "# Getting Startednn...",
  "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

Input:

Output:

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

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

json

{
  "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

Input:

Output:

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

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

json

{
  "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

Input:

Output:

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

json

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

View on GitHub

API Reference

Base URL

Authentication

Documentation Endpoints

GET /docs

POST /docs

GET /docs/{id}

PUT /docs/{id}

DELETE /docs/{id}

Project Taxonomy Endpoints

GET /project

GET /project/tree

POST /project/resolve

GET /project/{id}

PUT /project/{id}

Sync Endpoints

POST /sync/all

POST /sync/term/{id}

GET /sync/test-token

POST /sync/test-repo

POST /sync/setup

GET /sync/status

POST /sync/doc

POST /sync/batch

Error Responses

WP-CLI Commands

chubes project ensure

chubes project tree

chubes docs sync

Abilities (AI Agent Integration)

chubes/get-doc

chubes/search-docs

chubes/sync-docs

chubes/reset-documentation

More in Chubes Docs

Template Integration

Troubleshooting Guide

Usage Guide

Changelog

`chubes project ensure`

`chubes project tree`

`chubes docs sync`