> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON Import

> Import documents from JSON files into AGO

Import documents from JSON files into AGO. Use this connector for custom data sources, migrations, or bulk imports from any system that can export JSON.

## Overview

| Feature            | Details             |
| ------------------ | ------------------- |
| **Authentication** | None (file upload)  |
| **Content Type**   | Custom JSON data    |
| **Hierarchy**      | Flat (configurable) |
| **Bulk Import**    | Yes                 |

## Prerequisites

* JSON file with your documents
* Understanding of your data structure

## Configuration

### Required Fields

| Field         | Description                   | Example                    |
| ------------- | ----------------------------- | -------------------------- |
| `title_field` | Field name for document title | `title`, `name`, `heading` |

### Optional Fields

| Field            | Type   | Default       | Description                           |
| ---------------- | ------ | ------------- | ------------------------------------- |
| `content_fields` | array  | `["content"]` | Fields to combine as document content |
| `id_field`       | string | `id`          | Field name for unique identifier      |

## Setup Steps

1. Navigate to **Knowledge** → **Sources**
2. Click **Create Source**
3. Select **JSON** as the source type
4. Configure field mappings:
   * Set the title field
   * Set content field(s)
   * Set ID field (optional)
5. Click **Save**
6. Upload your JSON file via the sync interface

## JSON Format

### Basic Format

Array of objects with consistent structure:

```json theme={null}
[
  {
    "id": "doc-001",
    "title": "Getting Started",
    "content": "Welcome to our platform..."
  },
  {
    "id": "doc-002",
    "title": "Installation Guide",
    "content": "Follow these steps to install..."
  }
]
```

### Multiple Content Fields

Combine multiple fields into document content:

```json theme={null}
[
  {
    "id": "faq-001",
    "question": "How do I reset my password?",
    "answer": "Click on the forgot password link...",
    "category": "Account"
  }
]
```

Configuration:

```json theme={null}
{
  "title_field": "question",
  "content_fields": ["answer", "category"],
  "id_field": "id"
}
```

### Custom Field Names

Map any field structure:

```json theme={null}
[
  {
    "article_id": "KB001",
    "headline": "Troubleshooting Connection Issues",
    "body": "If you're experiencing connection problems...",
    "summary": "Quick fixes for common issues"
  }
]
```

Configuration:

```json theme={null}
{
  "title_field": "headline",
  "content_fields": ["summary", "body"],
  "id_field": "article_id"
}
```

## Uploading Files

### Via Admin Interface

1. Go to the JSON source in **Admin** > **Knowledge** > **Sources**
2. Click **Import** > **Upload File**
3. Select your JSON file
4. Monitor import progress

### Via API

```bash theme={null}
POST /api/knowledge-management/sync/upload-files
Content-Type: multipart/form-data

source_id: <source-uuid>
files: <your-file.json>
```

## Content Field Combination

When multiple content fields are specified, they are combined in order:

**Configuration:**

```json theme={null}
{
  "content_fields": ["summary", "description", "details"]
}
```

**Result:**

```
[summary content]

[description content]

[details content]
```

## Best Practices

### Data Preparation

* Ensure all objects have the same structure
* Use consistent field names
* Clean HTML or convert to Markdown before import
* Validate JSON syntax before upload

### Field Mapping

* Choose descriptive titles (not IDs or codes)
* Include all relevant content fields
* Use a unique ID field for updates

### Large Files

* For large datasets, consider splitting into smaller files
* Upload sequentially to avoid timeouts
* Monitor sync history for errors

## Migration Use Cases

### From Other Knowledge Bases

1. Export data from source system as JSON
2. Map fields to AGO's expected structure
3. Upload and verify import

### From Spreadsheets

1. Export spreadsheet to CSV
2. Convert CSV to JSON (many tools available)
3. Upload JSON to AGO

### From Databases

1. Export database query results as JSON
2. Transform field names if needed
3. Upload to AGO

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid JSON">
    * Validate JSON syntax (use online validators)
    * Check for trailing commas
    * Ensure proper quoting of strings
  </Accordion>

  <Accordion title="Missing Content">
    * Verify `content_fields` includes all needed fields
    * Check field names match exactly (case-sensitive)
    * Review for null or empty values
  </Accordion>

  <Accordion title="Duplicate Documents">
    * Use unique values in `id_field`
    * Re-importing updates existing documents by ID
    * Clear source before re-importing for fresh start
  </Accordion>

  <Accordion title="Encoding Issues">
    * Use UTF-8 encoding
    * Handle special characters properly
    * Convert from other encodings if needed
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Public API v1 Reference](../api/public-api-v1) - Complete API documentation
* [Knowledge Connectors](./knowledge-connectors) - All available connectors
* [Knowledge Source Management](../features/knowledge-source-management) - Source configuration
* [Knowledge AI Ingestion](../features/knowledge-ai-ingestion) - AI-powered import