Yuque

- 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

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

### 2. List User Repositories

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

### 3. List Repository Documents

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

### 4. Get Document Detail

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

### 5. Get Document Content (HTML/Markdown)

```bash
# 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

```bash
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

```bash
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:

```bash
# 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:

```json
{
  "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](references/api.md)
- Common Operations: See [references/examples.md](references/examples.md)