# Documents Guide

The Documents API provides access to technical documentation, datasheets, application notes, and other materials associated with Renesas products. This guide covers how to search, filter, and retrieve product documentation through the API.

## Overview

The Documents API enables you to:

- Search and browse technical documentation
- Filter documents by product, category, language, and date ranges
- Access multilingual versions of documents
- Retrieve documents by specific identifiers (DCP ID, Agile ID)


## Base Endpoints

- **GET** `/documents` - Retrieve a list of documents with filtering options
- **GET** `/documents/{dcp_id}` - Get a specific document by DCP Document ID
- **GET** `/documents/agile-id/{agile_id}` - Get a specific document by Agile ID


## Retrieving Documents

### Basic Request

Get a list of documents with default pagination:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents"
```

### Pagination

Control the number of results returned:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?limit=25&offset=50"
```

**Parameters:**

- `limit`: Number of results to return (1-100, default: 10)
- `offset`: Offset for pagination (default: 0)


## Filtering Options

### By Product

Find all documents related to a specific product:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?productId=RX71M"
```

### By Language

Filter documents by language:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?language=en"
```

**Supported languages:**

- `en` - English
- `ja` - Japanese
- `zh-hans` - Simplified Chinese


### By Document Category

Filter by document type or category:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?category=Datasheet"
```

### By DCP Document ID Prefix

Search for documents with specific DCP ID patterns:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?dcpDocumentIdStartsWith=R01DS"
```

### By Revision Date Range

Find documents revised within a specific time period:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?documentRevisionDateStart=2024-01-01&documentRevisionDateEnd=2024-12-31"
```

**Date format:** YYYY-MM-DD

## Response Structure

### Document Object

```json
{
  "agileId": "X1234567",
  "dcpDocumentId": "R01DS0001EJ0100",
  "category": [
    {
      "level": 1,
      "title": "Datasheet"
    },
    {
      "level": 2,
      "title": "Microcontrollers"
    }
  ],
  "product": [
    {
      "productId": "RX71M",
      "type": "Product",
      "title": "RX71M Microcontroller Series",
      "nid": "12345",
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "language": "en"
    }
  ],
  "title": "RX71M Group User's Manual: Hardware",
  "type": "User Manual",
  "fileType": "PDF",
  "secureDocument": false,
  "href": "https://www.renesas.com/sites/default/files/documents/products/microcontrollers/rx/rx700/rx71m/r01uw0111ej0200-rx71m.pdf",
  "revisionDate": "2024-03-15",
  "wwwUpdateDate": "2024-03-20",
  "language": "en",
  "nid": "67890",
  "uuid": "550e8400-e29b-41d4-a716-446655440001",
  "published": true,
  "featured": true,
  "filename": "r01uw0111ej0200-rx71m.pdf",
  "myrenesasDocument": false
}
```

### Key Fields Explained

**Identification:**

- `agileId`: Primary Agile system identifier
- `dcpDocumentId`: DCP (Document Control Portal) identifier
- `nid`: Drupal node ID
- `uuid`: Unique identifier


**Content Information:**

- `title`: Document title
- `type`: Document type (User Manual, Application Note, Datasheet, etc.)
- `fileType`: File format (PDF, DOCX, etc.)
- `language`: Document language code


**Associations:**

- `product`: Array of associated products with details
- `category`: Hierarchical categorization structure


**Access & Status:**

- `href`: Direct download URL
- `secureDocument`: Whether document requires special access
- `published`: Publication status
- `featured`: Whether document is highlighted/featured


## Multilingual Support

### Translation Information

Documents may have translations available:

```json
{
  "translation": [
    {
      "language": "ja",
      "dcpDocumentId": "R01DS0001JJ0100",
      "agileId": "X1234568",
      "title": "RX71M グループ ユーザーズマニュアル ハードウェア編",
      "href": "/documents/R01DS0001JJ0100"
    },
    {
      "language": "zh-hans",
      "dcpDocumentId": "R01DS0001CJ0100",
      "agileId": "X1234569",
      "title": "RX71M组 用户手册 硬件篇",
      "href": "/documents/R01DS0001CJ0100"
    }
  ]
}
```

### Finding Translated Versions

Search for documents in specific languages:

```bash
# Find all Japanese documentation for RX71M
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?productId=RX71M&language=ja"
```

## Getting Individual Documents

### By DCP Document ID

Retrieve a specific document using its DCP identifier:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents/R01DS0001EJ0100"
```

### By Agile ID

Retrieve a document using its Agile system identifier:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents/agile-id/X1234567"
```

## Common Use Cases

### Product Documentation Lookup

Find all documentation for a specific product:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?productId=RA6M4&limit=50"
```

### Recent Documentation Updates

Find recently updated documents:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?documentRevisionDateStart=2024-01-01"
```

### Application Notes Search

Find application notes by category:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?category=Application Note"
```

### Datasheet Retrieval

Get all datasheets for a product family:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.renesas.com/web-data/v1/documents?dcpDocumentIdStartsWith=R01DS&category=Datasheet"
```

## Document Categories

Documents are organized hierarchically. Common category structures include:

**Level 1 Categories:**

- Datasheet
- User Manual
- Application Note
- Reference Manual
- Release Note
- Errata
- Sample Code


**Level 2+ Subcategories:**

- Product families (Microcontrollers, Analog & Power, etc.)
- Functional areas (Hardware, Software, etc.)
- Specific topics (Communication, PWM, ADC, etc.)


## Error Handling

### Common Error Responses

**404 - Document Not Found:**

```json
{
  "error": "Document with DCP ID 'INVALID123' not found"
}
```

**400 - Invalid Parameters:**

```json
{
  "error": "Invalid language code. Supported values: en, ja, zh-hans"
}
```

## Best Practices

1. **Use Specific Filters**: Combine multiple filters to narrow results effectively
2. **Handle Languages**: Check for translated versions if serving international users
3. **Cache URLs**: Document URLs are stable and can be cached
4. **Check Revision Dates**: Monitor revision dates for important documents
5. **Validate Access**: Check `secureDocument` flag before direct access


## Integration Examples

### Python Example

```python
import requests
from datetime import datetime, timedelta

def get_recent_docs(product_id, api_key, days_back=30):
    \"\"\"Get documents updated in the last N days for a product\"\"\"
    
    end_date = datetime.now()
    start_date = end_date - timedelta(days=days_back)
    
    url = "https://api.renesas.com/web-data/v1/documents"
    headers = {"x-api-key": api_key}
    params = {
        "productId": product_id,
        "documentRevisionDateStart": start_date.strftime("%Y-%m-%d"),
        "documentRevisionDateEnd": end_date.strftime("%Y-%m-%d"),
        "language": "en"
    }
    
    response = requests.get(url, headers=headers, params=params)
    if response.status_code == 200:
        return response.json()
    else:
        response.raise_for_status()

# Usage
recent_docs = get_recent_docs("RX71M", "your-api-key", 60)
for doc in recent_docs:
    print(f"{doc['title']} - {doc['revisionDate']}")
```

### JavaScript Example

```javascript
async function findDatasheets(productFamily, apiKey) {
    const url = new URL('https://api.renesas.com/web-data/v1/documents');
    url.searchParams.append('dcpDocumentIdStartsWith', 'R01DS');
    url.searchParams.append('category', 'Datasheet');
    url.searchParams.append('language', 'en');
    url.searchParams.append('limit', '50');
    
    const response = await fetch(url, {
        headers: {
            'x-api-key': apiKey
        }
    });
    
    if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
    }
    
    const documents = await response.json();
    
    // Filter by product family if needed
    if (productFamily) {
        return documents.filter(doc => 
            doc.product.some(p => 
                p.productId.includes(productFamily) || 
                p.title.toLowerCase().includes(productFamily.toLowerCase())
            )
        );
    }
    
    return documents;
}
```

## Document Security and Access

### Secure Documents

Some documents may require special access permissions:

```json
{
  "secureDocument": true,
  "myrenesasDocument": true,
  "href": "https://www.renesas.com/secure-docs/rx71m-restricted.pdf"
}
```

When `secureDocument` is `true`, users may need:

- MyRenesas account login
- Special permissions or agreements
- Corporate account access


### Public Documents

Most technical documentation is publicly accessible:

```json
{
  "secureDocument": false,
  "href": "https://www.renesas.com/sites/default/files/documents/products/microcontrollers/rx/rx700/rx71m/r01uw0111ej0200-rx71m.pdf"
}
```

## Related Resources

- [Product Parts Guide](/guides/product-parts) - Find products and their associated documentation
- [Authentication Guide](/guides/authentication) - API key setup and security
- [Quickstart Guide](/guides/quickstart) - Getting started with the API