Skip to main content

Syncing your knowledge base from an external system

Keep your agent's knowledge base matched to ServiceNow, Google Drive, or a custom API with a nightly sync.

External sources keep your agent's knowledge base matched to a knowledge base your institution already maintains, such as ServiceNow or Google Drive. Once a sync is set up, new and edited articles in your system come into CollegeVine automatically every night. You don't need to upload them by hand.


How it works

  • Nightly updates. The sync runs once a night. Changes you publish in your system are picked up on the next nightly run.

  • New articles are added automatically. Any new article in a synced knowledge base or folder is picked up and tagged on the next run.

  • Edits replace the old version. When you update an article in your system, the next run replaces the CollegeVine copy.

  • Tags are applied for you. Every synced article gets the tags set on its sync, so it lands in the right agent's scope without manual tagging.


Is your system a good fit?

External sources work best for reference content that changes from time to time, like help articles, policies, and handbooks. The sync needs access to a list of records and their content, using an API with a standard sign-in method such as an API key or OAuth.

💡 There are two ways to set up a sync:

  1. Your system already has a usable document API. Give a service account read access to the appropriate content and endpoints, and share its credentials securely with your CollegeVine team.

  2. Your system doesn't have a usable API. Your technical team can build a listing endpoint and a content endpoint that returns each record in a supported format. See the custom API setup and worked examples below.

External sources aren't a fit when you can't provide an API listing the content to sync, or for data that changes hourly, like live availability or ticket counts. Event listings work fine if a nightly refresh is often enough. Your CollegeVine team can suggest other options.


Option 1: Your system already has a document API

Your CollegeVine team handles the setup. Grant a service account read access to the appropriate API endpoints and content, then provide the details below.

What you'll need to provide

  1. Your system's address, for example yourschool.service-now.com.

  2. API credentials for a service account. Your CollegeVine team will tell you how to share these securely. Don't send credentials over email or chat.

  3. Which knowledge bases or folders to include. Only share the ones you want your agent to use. Many systems also have internal IT or HR knowledge bases that should stay out.

  4. Confirmation that the service account can read every article in scope. Articles the account can't see won't sync, and the sync doesn't report them as missing.


Option 2: Build a custom API

If your system doesn't have a usable document API, your technical team can create the endpoints below and use the worked examples as a guide. Your CollegeVine team will configure the sync using the details you provide.

What your system needs

The sync needs two endpoints on the API host you provide:

  1. A listing endpoint

  2. A content endpoint

These can read from your existing website CMS or events system. You don't need a second document library or a separate file for each record.

Listing endpoint

The listing endpoint returns the records you want to sync. Each record needs a stable ID, a title, and a version value that changes when its content changes. If a title is missing, the sync uses the ID as the title.

For example, GET /api/kb/pages?skip=0&take=50 could return:

{
  "pages": [
    {
      "id": "page-001",
      "title": "Housing help",
      "updated_at": "2026-10-27T14:00:00Z"
    },
    {
      "id": "page-002",
      "title": "Campus resources",
      "updated_at": "2026-10-20T09:30:00Z"
    }
  ]
}

The sync reads the ID, title, and version from each record, then uses the ID to request its content separately.

Content endpoint

The content endpoint accepts a record's ID and returns its content directly in a supported format: HTML, Markdown, plain text, PDF, Word, Excel, or CSV.

For example, GET /api/kb/pages/page-001/content could return this body with Content-Type: text/markdown:

# Housing helpStudents can contact the Housing Office for help with campus housing.More information: https://www.example.edu/housing

The endpoint can look up the record in your CMS or events system and format the response when requested. It does not need to return a JSON wrapper. For events, include the description, dates, location, and the link people should use to view or register for the event. The sync requests the configured content endpoint. It does not fetch a url field from the listing.

Your field names and endpoint paths can differ from these examples, since they are mapped in the sync settings. See the worked examples below for complete page and event configurations.

Pagination and page-size limits

If your listing is paginated, the sync's Page size must match a value your API supports. For an offset-based API, the sync can send requests such as ?skip=0&take=50, then ?skip=50&take=50 to get the next set of records.

  • take is the number of records requested in one response.

  • skip is how many records to pass over first.

Keep the ordering stable between requests so records don't move from one page to another while the sync is reading them. If one response returns the whole list, choose Single page and leave pagination parameters out.

The sync reads up to 100 pages per run and has 10 minutes to finish reading the listing. With offset pagination, it considers the listing complete when a page contains fewer records than requested. If it reaches 100 full pages, the run fails safely and makes no additions, updates, or removals from that run.

Choose a page size that your API honors and that lets the full listing finish within the limit. If the API returns a totalItems count, you can include it, but the sync does not use that count to detect the end. It looks for a short final page. With cursor pagination, the response should include a next cursor until the last page, then omit it.

Tracking content changes

Each listing record needs a value that tracks its content version, such as a last-updated date or a content_hash. The sync compares this value with the one it saw on the previous run. If the record is new or the value has changed, the sync downloads its content. If the value is unchanged, it skips the download.

The value must change whenever the content returned by the content endpoint changes, and stay the same when the content has not changed. For example:

{
  "items": [
    {
      "id": "event-001",
      "name": "Campus tour",
      "content_hash": "cdd27334bf59ca238d95e9172db748219ca0404225fa33becd0a7c4f3a5610ba"
    }
  ]
}

An event's hash can be based on its name, description, start and end times, location, and registration URL. Don't use the current time, because that would make every event look new on every run. Your CollegeVine team can help your web team choose the right fields.

Custom API sync settings

Sync settings tell the sync where to find your records, how to spot changes, and where to download each record's content.

Setting

What it tells the sync

Example values

Source

Which saved API connection to use. It contains the API host and credentials.

The connection for api.example.edu

Listing path

Which endpoint returns the list of records.

/api/kb/pages

Listing query parameters

Which parameters to send when requesting the list. Leave blank if the endpoint needs none.

{"skip":"%{offset}","take":"%{page_size}"}

Pagination

How to request the whole list. Choose Single page if the full list comes back in one response, Offset for skip/take, or Cursor if the API returns a next-page cursor.

Offset

Page size

How many records to request per offset page. It must be at or below the API's maximum.

50

Cursor path

For cursor pagination, where to find the next cursor in the listing response.

next_cursor

Documents path

Where the array of records is in the listing response. Use dots for nested fields.

pages or data.articles

Identifier path

Which field holds each record's stable ID. The sync puts this value into the Download path.

id

Title path

Which field supplies the article title. If it is missing, the ID is used as the title.

title

Version path

Which field changes when the content changes. If it is unchanged, the sync skips downloading that record.

updated_at or content_hash

Download path

The endpoint to fetch one record's content. %{external_id} is replaced with that record's ID.

/api/kb/pages/%{external_id}/content

Tags

Which knowledge base tags to apply to synced records.

Housing, Student Support

Enabled

Whether the scheduled sync runs. A disabled sync is skipped and its existing articles remain in the knowledge base.

On

For example, if the listing returns a record with id: "page-001", the configured Download path becomes /api/kb/pages/page-001/content. The sync requests that endpoint when the record is new or its version value changed. It reads the content from that response and does not open a url field from the listing.

What you'll need to provide for a custom API

After creating the custom endpoints, your CollegeVine team handles the sync configuration. To get started, send them:

  1. Your API host and endpoint paths. For example, api.example.edu, /api/kb/pages, and /api/kb/pages/{id}/content. The listing and content endpoints should use the API host configured for the integration.

  2. API credentials for a service account. The account must be able to read every record you want synced. Your CollegeVine team will tell you how to share credentials securely. Don't send them over email or chat.

  3. The records to include. Tell us which knowledge bases, folders, or event types to include, and any filters such as "published pages" or "upcoming public events." Records the service account can't read won't sync.

  4. Your field names and version method. Identify the fields for record ID, title, and last-updated date or content hash. If the source has no last-updated date, tell us how you will provide a stable version value.

  5. Your pagination details. Tell us whether the listing uses skip and take, a cursor, or returns everything in one response. For skip and take, include the largest take value your API supports. The configured page size must not be larger than that limit.

  6. Sample responses. Share sanitized examples of one listing response and one content response for each type of source, such as pages and events. Replace real names, IDs, and URLs with examples. This lets your CollegeVine team confirm the fields and formats before the endpoints are finished.


Tags for either setup

💡 Let your CollegeVine team know which tags in your knowledge base you'd like applied to content brought in by the sync. A sync can have many tags. Content that needs different tags should be set up as separate syncs.


What changes in your knowledge base

When external sources are turned on, changes made in your CollegeVine Knowledge section go live right away. Uploading, editing, or deleting an asset no longer creates a draft. The Publish button and the pending changes list go away.

Bulk upload, tags, and everything else in your knowledge base work the same as before. Changes made in your own system still arrive with the nightly sync.


What syncs and what doesn't

The record's content syncs, but linked images and attachments do not. Keep these limits in mind:

  • Images and screenshots aren't synced. If key steps appear only in a screenshot, add them to the article text so your agent can use them.

  • Attachments aren't synced. If an article links to a PDF or Word file, your agent sees the link but can't read the file. Upload important attachments to your knowledge base directly, and replace them when they change.

  • Links come through as clickable text. Your agent can point people to linked pages but can't read them.


Removing content

When you remove or unpublish an article in your system, it stays in CollegeVine for 1 to 2 days before the sync removes it. During that time, your agent can still answer from it.

If your agent needs to stop using an article right away (for example, it contains wrong or sensitive information), contact your CollegeVine team and tell them which article. They'll remove it by hand.

💡 If you later edit an article that was removed by hand, the sync will bring it back on the next run.


Worked examples for a custom API

These examples show how to build the listing and content endpoints for option 2.

Example: website pages

This example lists website pages, returns each page as Markdown, and shows the matching sync configuration.

Listing response: GET /api/kb/pages?skip=0&take=50

{
  "pages": [
    {
      "id": "page-001",
      "title": "Housing help",
      "updated_at": "2026-10-27T14:00:00Z"
    },
    {
      "id": "page-002",
      "title": "Campus resources",
      "updated_at": "2026-10-20T09:30:00Z"
    }
  ]
}

Content response: GET /api/kb/pages/page-001/content, with Content-Type: text/markdown

# Housing helpStudents can contact the Housing Office for help with campus housing.More information: https://www.example.edu/housing

Example page configuration:

Listing path: /api/kb/pages
Pagination: Offset
Page size: 50
Query template: {"skip":"%{offset}","take":"%{page_size}"}
Documents path: pages
Identifier path: id
Title path: title
Version path: updated_at
Download path: /api/kb/pages/%{external_id}/content

Example: upcoming events

Your listing endpoint can filter to upcoming public events. It can include the event URL, but the sync will not fetch that URL. Add a content_hash that changes when the event content changes. For example:

{
  "skip": 0,
  "take": 50,
  "totalItems": 1,
  "items": [
    {
      "id": "event-001",
      "name": "Campus tour",
      "content_hash": "cdd27334bf59ca238d95e9172db748219ca0404225fa33becd0a7c4f3a5610ba",
      "url": "https://events.example.edu/events/event-001"
    }
  ]
}

The sync then requests GET /api/kb/events/event-001/content. That endpoint can look up the event in your events system and return its content as Markdown with Content-Type: text/markdown:

# Campus tourJoin us for a guided tour of campus.When: 2027-02-02 10:00–11:00 a.m. ET
Location: Welcome Center
Register: https://events.example.edu/events/event-001

The hash above is the SHA-256 of the exact Markdown response shown, including its line breaks and a final newline. If the title, description, dates, location, or registration link changes, the hash changes and the sync downloads the updated event.

Example event configuration:

Listing path: /api/kb/events
Pagination: Offset
Page size: 50
Query template: {"skip":"%{offset}","take":"%{page_size}"}
Documents path: items
Identifier path: id
Title path: name
Version path: content_hash
Download path: /api/kb/events/%{external_id}/content

Related articles

Did this answer your question?