---
title: "Add a source."
method: POST
path: "/api/v1/projects/{projectId}/sources"
tags: ["Sources"]
---

# Add a source.

`POST /api/v1/projects/{projectId}/sources`

## Request

- Base URL: `https://app.customgpt.ai`
- URL: `https://app.customgpt.ai/api/v1/projects/{projectId}/sources`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/poll-the-people/apis/customgpt-ai/docs/api/v1/projects/:projectId/sources/post.ts> (a function with typed inputs; its response is checked against the schema)

Connects a new data source to an agent's knowledge base. You can add content via sitemap URL, file upload, or integration connection (Google Drive, SharePoint, etc.). The system will begin indexing the content immediately.

Notes: For large sources, indexing may take several minutes. Check the source status to monitor progress.

## Path parameters

- `projectId` integer, required

## Request body `multipart/form-data`

- object
  - `sitemap_path` string: Supports YouTube, Vimeo, sitemaps, and websites.
  - `type` 'sitemap' | 'web-images' | 'upload': The source type. Use `web-images` with image extraction modes such as `images-sitemap` or `images-opengraph`.
  - `file_data_retension` boolean: File data retension
  - `is_ocr_enabled` 0 | 1 | 2: OCR processing mode: 0 = Disabled, 1 = OCR enabled, 2 = AI Vision
  - `is_anonymized` boolean: Anonymized
  - `file` string, binary: Single file upload as a data source. Discouraged — use `files[]` instead for new integrations. Supported types include documents, audio files, and images. Images require `is_vision_enabled: true` on the agent. Max file size: 100 MB.
  - `files[]` string[]: Multiple file uploads. Submit each file as a separate `files[]` part in multipart/form-data. Up to 50 files per request, max 100MB each, max 1GB total batch size.
  - `is_vision_enabled` boolean: Whether to enable vision processing for images in the file source.
  - `is_vision_compress_image` boolean: Whether to compress images for vision processing.
  - `image_extraction_type` 'none' | 'sync_from_sitemap' | 'extract_opengraph_images': The method used for extracting images from the website.
  - `sync_all_images` boolean: When extracting images from a sitemap, sync every image on a page instead of only the first one. Each synced image consumes one vision credit.
  - `is_low_performance_mode_enabled` boolean: Use a lower-performance crawl mode that is less likely to be blocked by websites with aggressive bot protection.
  - `allow_extra_timeout` boolean: Allow extra processing time when crawling slow or large sources.
  - `use_full_url_crawl` boolean: Crawl every URL discovered on the site rather than relying solely on the sitemap.

## Response `201`

Successfully created a new agent source.

- object
  - `status` 'error' | 'success': The status of the response
  - `data` ProjectSource
    - `id` integer: The agent source ID
    - `created_at` string, date-time: The agent source creation date
    - `updated_at` string, date-time: The agent source update date
    - `type` 'sitemap' | 'web-images' | 'upload': The source type.
    - `sub_type` 'readme' | 'gitbook' | 'document360' | 'knowledgeowl' | 'wordpress' | 'wix' | 'webflow' | 'framer' | 'squarespace' | 'weebly' | 'ghost' | 'shopify' | 'magento' | 'bigcommerce' | 'woocommerce' | 'hubspot' | 'url-list' | 'rss' | 'podcast' | 'web-search' | 'extra_timeout' | 'low_performance' | 'archive' | 'images-sitemap' | 'images-opengraph' | 'zendesk_articles' | 'zendesk_tickets' | 'freshdesk_tickets', nullable: The source subtype. Generic web image sources use `images-sitemap` or `images-opengraph`; e-commerce sources keep their platform subtype.
    - `settings` object: The agent source settings
      - `executive_js` boolean: Whether the agent source should execute JavaScript
      - `data_refresh_frequency` 'never' | 'daily' | 'weekly' | 'monthly' | 'advanced': How often the source content is automatically refreshed.
      - `create_new_pages` boolean: Add new pages to agent automatically during refresh agent source
      - `remove_unexist_pages` boolean: Remove pages from agent automatically during refresh agent source
      - `refresh_existing_pages` 'never' | 'always' | 'if_updated': Whether existing pages are re-crawled during a refresh.
      - `sitemap_path` string: The agent source sitemap path
      - `image_extraction_type` 'none' | 'sync_from_sitemap' | 'extract_opengraph_images': The method used to extract images from web sources.
      - `update_existing_images` boolean: Whether to update existing images during refresh.
      - `sync_all_images` boolean: When extracting images from a sitemap, sync every image on a page instead of only the first one. Each synced image consumes one vision credit.
    - `pages` Page[], nullable: The agent source pages
      - `id` integer: Page ID
      - `page_url` string: URL of the document
      - `page_url_hash` string, md5: Hash of the URL of the document
      - `project_id` integer: Agent ID
      - `s3_path` string, nullable: This is the path where the document is stored in S3.\nNote: This is omitted in the response if the document is not a file
      - `crawl_status` 'ok' | 'queued' | 'failed' | 'n/a' | 'limited': The fetch step status — whether the page URL was successfully reached and its content fetched. Values: - `ok`: fetched successfully. - `queued`: waiting to be fetched. - `failed`: fetch attempt failed. - `limited`: fetched but content was truncated. - `n/a`: not applicable for this source type.
      - `index_status` 'ok' | 'queued' | 'failed' | 'n/a' | 'limited': The indexing step status — whether the fetched content has been processed and added to the agent's knowledge base. Values: - `ok`: indexed successfully. - `queued`: waiting to be indexed. - `failed`: indexing failed. - `limited`: partially indexed. - `n/a`: not applicable for this source type. Note: `crawl_status` can be `ok` while `index_status` is `queued` — fetch succeeded but ingestion is still pending.
      - `is_file` boolean: Whether the document is a file or not
      - `is_refreshable` boolean: Whether the document can be refreshed or not
      - `is_file_kept` boolean: Whether the file is kept after processing or not.\nNote: This is omitted in the response if the document is not a file
      - `filename` string, nullable: Filename of the document.\nNote: This is omitted in the response if the document is not a file
      - `filesize` integer, nullable: Filesize of the document.\nNote: This is omitted in the response if the document is not a file
      - `created_at` string, date-time: Date and time when the document was created
      - `updated_at` string, date-time: Date and time when the document was updated
      - `deleted_at` string, date-time: Date and time when the document was deleted

## Other responses

- `400`: Service unavailable
- `401`: API Token is either missing or invalid
- `404`: Agent not found
- `429`: Too many requests. You have exceeded your API rate limit.
- `500`: Internal Server Error

## Changes

- **2026-11-03** `77aab4354382`: 2 breaking, 13 warning, 19 info
  - request property `is_ocr_enabled` was restricted to a list of enum values
  - the `is_ocr_enabled` request property type changed from `boolean` to `integer`
  - added the new `422.00` enum value to the `data/code` response property for the response status `400`
  - added the new `422.00` enum value to the `data/code` response property for the response status `401`
  - …30 more
- **2026-07-17** `b80e6dfcf78d`: 1 breaking, 4 warning, 11 info
  - the `data/pages/items/filename` response's property format changed from `binary` to no format for status `201`
  - removed the optional property `data/settings/data_refresh` from the response with the `201` status
  - added the new `Agent id is required` enum value to the `data/message` response property for the response status `404`
  - added the new `Agent with id {projectId} not found` enum value to the `data/message` response property for the response status `404`
  - …12 more
- **2023-07-12** `1675fc6aa16a`: 1 breaking, 1 info
  - removed the success response with the status `200`
  - added the success response with the status `201`
- **2023-07-05** `3033527b3d74`: 1 info
  - endpoint added
- **2023-06-02** `1842d7fd0430`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/poll-the-people/apis/customgpt-ai/changes/api/v1/projects/:projectId/sources/post.md)

---

[API](https://skmtc.dev/poll-the-people/apis/customgpt-ai.md) - [All operations](https://skmtc.dev/poll-the-people/apis/customgpt-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/poll-the-people/apis/customgpt-ai/revisions/77aab4354382?raw)