API Documentation Writing Guide

This document defines the unified structure and writing conventions for API module documentation in the docs/en/api/ directory.

Directory Structure

API documentation is organized by module, with one file per module, using a two-digit numerical prefix.

Unified File Structure

Each API module documentation should follow the structure below:

markdown

# Module Name

Brief introduction explaining the main features and purpose of this module.

## Optional Concepts/Introduction Section

(If needed, explain core concepts, workflows, etc., related to this module)

## API Reference

### API Method Name 1

#### 1. API Implementation Introduction

Explain the purpose of this API, point to the corresponding code entry, and briefly describe the principles and workflow.

**Code Entry**:
- `openviking/<module>/<file>.py:<ClassName>.<MethodName>` - Core implementation
- `openviking/server/routers/<router-file>.py` - HTTP router
- `openviking_cli/commands/<command-file>.py` - CLI command

#### 2. Interface and Parameter Description

**Parameters**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| <param-name> | <type> | <yes/no> | <default> | <detailed description> |
| ... | ... | ... | ... | ... |

**Optional Supplementary Section**

(If needed, explain special behaviors, considerations, usage scenarios, etc.)

#### 3. Usage Examples

**Python SDK**

```python
<SDK call example>
```

**TypeScript SDK**

```typescript
<SDK call example>
```

**Go SDK**

```go
<SDK call example>
```

**HTTP API**

```
<HTTP Method> <Path>
```

```bash
<curl example>
```

**CLI**

```bash
<CLI command example>
```

**Response Example**

```json
<JSON response example>
```


#### 4. Response Example, Error Handling, and Exception Handling (Optional)

---

### API Method Name 2

(Repeat the above structure)

---

## Optional Additional Sections

## Related Documentation

- [Document Title](<relative-path>) - <brief description>

Structure Details

Title and Introduction

The level 1 heading is the module name
The introduction uses a paragraph to explain the purpose and main features of the module

API Reference Section

Each API is organized in the following three parts:

1. API Implementation Introduction

Explain the purpose of this API
Provide code entry paths for readers to reference the source code
Briefly describe the implementation principles and processing workflow

Code Entry Notes:

Core implementation: points to the main business logic code
HTTP router: points to the FastAPI route definition
CLI command: points to the CLI command implementation (if available)

2. Interface and Parameter Description

Parameter table: includes parameter name, type, required status, default value, description
Supplementary notes (optional): special behaviors, considerations, usage scenarios, etc.

3. Usage Examples

When an operation presents all transports together, prefer this order:

Python SDK example
TypeScript SDK example
Go SDK example, when it adds endpoint-specific value and can stay concise
HTTP API (method + path + curl example)
CLI example
Response example

For an existing operation with a workflow-specific structure, keep the local structure stable and place TypeScript next to the other SDK examples.

Keep API documentation organized around API modules and individual operations, not around client languages. SDK snippets should be short call examples inside the relevant operation's Usage Examples. Put language-specific quick references, walkthroughs, and combined workflows in that SDK's own documentation instead of adding language-owned sections to API module pages.

Example: Complete API Documentation

markdown

### add_resource()

#### 1. API Implementation Introduction

Add resources to the knowledge base, supporting various sources such as local files, directories, URLs, etc.

**Processing Workflow**:
1. Identify resource type (local file/directory/URL)
2. Call corresponding parser to parse content
3. Build directory tree and write to AGFS
4. Asynchronously generate L0/L1 semantic abstracts
5. Build vector index

**Code Entry**:
- `openviking/core/client.py:OpenViking.add_resource()` - SDK entry
- `openviking/resource/importer.py:ResourceImporter.import_resource()` - Core implementation
- `openviking/server/routers/resources.py` - HTTP router
- `openviking_cli/commands/resources.py` - CLI command

#### 2. Interface and Parameter Description

**Parameters**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| path | str | Yes | - | Local path, directory path, or URL |
| to | str | No | None | Target Viking URI (must be within the resources scope) |
| reason | str | No | "" | Reason for adding this resource |
| wait | bool | No | False | Whether to wait for semantic processing completion |

**Notes**

- SDK/CLI can directly pass local paths; raw HTTP requires `temp_upload` first
- When `to` is specified and the target already exists, an incremental update process is used

#### 3. Usage Examples

**HTTP API**

```
POST /api/v1/resources
```

```bash
curl -X POST http://localhost:1933/api/v1/resources \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "path": "https://example.com/guide.md",
    "reason": "User guide documentation",
    "wait": true
  }'
```

**Python SDK**

```python
import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

result = client.add_resource(
    "./documents/guide.md",
    reason="User guide documentation"
)
print(f"Added: {result['root_uri']}")

client.wait_processed()
```

**CLI**

```bash
openviking add-resource ./documents/guide.md --reason "User guide documentation" --wait
```

**Response Example**

```json
{
  "status": "ok",
  "result": {
    "status": "success",
    "root_uri": "viking://resources/documents/guide.md",
    "source_path": "./documents/guide.md",
    "errors": []
  },
  "time": 0.123
}
```

---

Documentation Maintenance Checklist

When adding or modifying API documentation, please check:

Implementation introduction is clear and code entry paths are correct
Parameter table is complete and accurate
Example code is concise and runnable
HTTP method and path are correct
Response example matches actual output