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:

[
  {
    "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:

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

Configuration:

{
  "title_field": "question",
  "content_fields": ["answer", "category"],
  "id_field": "id"
}

Custom Field Names

Map any field structure:

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

Configuration:

{
  "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

Automation tools (n8n, Zapier, your own scripts) send the records directly to the Public API v1 instead of uploading a file. Give each document a page_id — your own identifier for that record. Sending the same page_id again updates the document rather than creating a duplicate, so you can re-run the same sync as often as you like.

POST https://<your-tenant>.api.useago.com/api/v1/documents/bulk
X-API-Key: <your-api-key>
Content-Type: application/json

{
  "items": [
    {
      "source_id": "<source-uuid>",
      "page_id": "KB001",
      "title": "Troubleshooting Connection Issues",
      "content": "Quick fixes for common issues\n\nIf you're experiencing connection problems..."
    }
  ]
}

The response tells you what was created, what was updated, and which items failed:

{
  "object": "bulk_result",
  "created": [],
  "updated": [{ "object": "document", "id": "...", "page_id": "KB001" }],
  "errors": [],
  "total_created": 0,
  "total_updated": 1,
  "total_errors": 0
}

To remove records that no longer exist upstream, delete them with the same identifiers:

POST https://<your-tenant>.api.useago.com/api/v1/documents/bulk-delete
X-API-Key: <your-api-key>
Content-Type: application/json

{
  "source_id": "<source-uuid>",
  "page_ids": ["KB001", "KB002"]
}

not_found comes back as page_id values, so you can match it against your own records.

Both endpoints accept up to 100 items per request, and need an API key with the knowledge:write scope. When you send records this way, you choose the title and content yourself, so the field mapping configured on the source does not apply.

Content Field Combination

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

Configuration:

{
  "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

Invalid JSON

• Validate JSON syntax (use online validators)
• Check for trailing commas
• Ensure proper quoting of strings

Missing Content

• Verify content_fields includes all needed fields
• Check field names match exactly (case-sensitive)
• Review for null or empty values

Duplicate Documents

• Use unique values in id_field
• Re-importing updates existing documents by ID
• Clear source before re-importing for fresh start

Encoding Issues

• Use UTF-8 encoding
• Handle special characters properly
• Convert from other encodings if needed

Related Documentation

• Public API v1 Reference - Complete API documentation
• Knowledge Connectors - All available connectors
• Knowledge Source Management - Source configuration
• Knowledge AI Ingestion - AI-powered import