Yuque Skill

Interact with Yuque (语雀) knowledge base platform via the Yuque Open API.

Prerequisites

• Yuque API Token (stored in environment variable YUQUE_TOKEN)
• Base URL: https://www.yuque.com/api/v2

Authentication

All API requests require an X-Auth-Token header with your Yuque token.

Core Workflows

1. Get User Info

curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/user

2. List User Repositories

curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/users/<login>/repos

3. List Repository Documents

curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/repos/<namespace>/docs

4. Get Document Detail

curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/repos/<namespace>/docs/<slug>

5. Get Document Content (HTML/Markdown)

# Get HTML content
curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/repos/<namespace>/docs/<slug>?raw=1

# Get Markdown content
curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/repos/<namespace>/docs/<slug>?raw=1 | python scripts/parse_yuque.py --format md

6. Create Document

curl -s -X POST \
  -H "X-Auth-Token: $YUQUE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Document Title", "body": "Document content in Markdown"}' \
  https://www.yuque.com/api/v2/repos/<namespace>/docs

7. Update Document

curl -s -X PUT \
  -H "X-Auth-Token: $YUQUE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title", "body": "Updated content"}' \
  https://www.yuque.com/api/v2/repos/<namespace>/docs/<id>

8. Search Documents

Yuque API doesn't have a direct search endpoint. Use list + filter approach:

# List all docs in a repo and filter by title
python scripts/search_yuque.py --namespace <namespace> --query "keyword"

Common Namespace Formats

• Personal repo: username/repo-slug
• Team repo: teamname/repo-slug

Response Format

All API responses are JSON with this structure:

{
  "data": { ... },
  "meta": { ... }
}

Error Handling

Common HTTP status codes:

• 401: Unauthorized (check token)
• 403: Forbidden (no permission)
• 404: Resource not found
• 429: Rate limited (wait and retry)

Helper Scripts

Use the provided Python scripts for common operations:

• scripts/yuque_cli.py - Full CLI for Yuque operations
• scripts/parse_yuque.py - Parse Yuque HTML to Markdown
• scripts/search_yuque.py - Search documents in repositories

References

• API Documentation: See references/api.md
• Common Operations: See references/examples.md