--- title: "Create an ingest job" method: POST path: "/v1/namespace/{namespaceId}/ingest-jobs" tags: ["Ingest Jobs"] --- # Create an ingest job `POST /v1/namespace/{namespaceId}/ingest-jobs` Create an ingest job for the authenticated organization. You can control how documents are parsed and chunked using the optional `config` object (for example, chunk size, overlap, language, and advanced OCR/LLM options). ## Path parameters - `namespaceId` string, required — The id of the namespace (prefixed with ns_) ## Headers - `x-tenant-id` string — Optional tenant id to use for the request. If not provided, the namespace will be used directly. Must be alphanumeric and up to 64 characters. ## Request body - object - `name` string, nullable — The name of the ingest job. - `payload` union, required — The ingest job payload for creation. - object - `type` 'TEXT', required - `fileName` string, nullable — The name of the file. - `text` string, required — The text to ingest. - object - `type` 'FILE', required - `fileUrl` string, uri, required — The URL of the file to ingest. - `fileName` string, nullable — The name of the file. - object - `type` 'MANAGED_FILE', required - `key` string, required — The key of the managed file to ingest. - `fileName` string, nullable — The name of the file. - object - `type` 'CRAWL', required - `url` string, uri, required — The starting URL to crawl. - `maxDepth` integer — Maximum depth to follow links from the starting URL. Depth 1 means only the initial page. Defaults to `5`. - `limit` integer — Maximum number of pages to crawl before stopping. Helps bound large sites. Defaults to `50`. - `includePaths` string[] — Only crawl URLs whose path matches at least one of these prefixes. - `excludePaths` string[] — Never crawl URLs whose path matches these prefixes. - `headers` object — Custom HTTP headers to send with crawl requests (for example, auth headers). - object - `type` 'YOUTUBE', required - `urls` string[], required — The URLs of videos, channels, or playlists (hostname must be www.youtube.com or youtu.be). - `transcriptLanguages` LanguageCode[] — We will try to fetch the first available transcript in the given languages. Default is `en`. - `includeMetadata` boolean — Whether to include metadata in the ingestion (like video description, tags, category, duration, etc...). Defaults to `false`. - object - `type` 'BATCH', required - `items` union[], required — The items to ingest. - union - object - `type` 'TEXT', required - `fileName` string, nullable — The name of the file. - `text` string, required — The text to ingest. - `config` DocumentConfig — The document config. - … - object - `type` 'FILE', required - `fileUrl` string, uri, required — The URL of the file to ingest. - `fileName` string, nullable — The name of the file. - `config` DocumentConfig — The document config. - … - object - `type` 'MANAGED_FILE', required - `key` string, required — The key of the managed file to ingest. - `fileName` string, nullable — The name of the file. - `config` DocumentConfig — The document config. - … - `config` IngestJobConfig — The ingest job config. - `chunkSize` integer — Chunk size (in characters). Controls approximately how much text is included in each chunk. Defaults to `2048`. - `delimiter` string — Delimiter to use for separating text before chunking. - `metadata` object — Custom metadata to be added to the ingested documents. It cannot contain nested objects; only string, number, boolean, and array of strings are allowed. - `languageCode` 'af' | 'am' | 'ar' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'en' | 'es' | 'et' | 'fa' | 'fi' | 'fr' | 'ga' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'is' | 'it' | 'jp' | 'kr' | 'lt' | 'lv' | 'mk' | 'ms' | 'mt' | 'ne' | 'nl' | 'no' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'sw' | 'ta' | 'te' | 'th' | 'tl' | 'tr' | 'uk' | 'ur' | 'vi' | 'zh' | 'zu' - `mode` 'fast' | 'balanced' | 'accurate' — Processing mode for the parser. `fast` favors speed, `accurate` (pro subscription only) favors quality and layout fidelity, and `balanced` offers a compromise between the two. Defaults to `balanced`. - `disableImageExtraction` boolean — Disable image extraction from the document. When combined with `useLlm`, images may still be automatically captioned by the partition API. Defaults to `false`. - `disableImageCaptions` boolean — Disable synthetic image captions/descriptions in output. Images will be rendered as plain img tags without alt text. Defaults to `false`. - `chartUnderstanding` boolean — Enable chart understanding. This will extract the data from the charts in the document. Defaults to `false`. - `keepPageheaderInOutput` boolean — Keep the page header in the output. Defaults to `false`. - `keepPagefooterInOutput` boolean — Keep the page footer in the output. Defaults to `false`. - `forceOcr` boolean — Force OCR on the document even if selectable text exists. Useful for scanned documents with unreliable embedded text. Defaults to `false`. - `disableOcrMath` boolean — Disable inline math recognition in OCR. This can be useful if the document contains content that is frequently misclassified as math. Defaults to `false`. - `useLlm` boolean — Enable LLM-assisted parsing to improve tables, forms, inline math, and layout detection. May increase latency and token usage. Defaults to `true`. - `chunkOverlap` number — [Deprecated] Custom chunk overlap (in characters) between consecutive chunks. Helps preserve context across chunk boundaries. - `maxChunkSize` number — [Deprecated] Hard chunk size. This option is ignored by the current partition pipeline and kept only for backwards compatibility. - `chunkingStrategy` 'basic' | 'by_title' — [Deprecated] The legacy chunking strategy. This option is ignored by the current partition pipeline and kept only for backwards compatibility. - `strategy` 'auto' | 'fast' | 'hi_res' | 'ocr_only' — [Deprecated] Legacy processing strategy used by the previous partition API. This option is ignored by the current pipeline and kept only for backwards compatibility. - `externalId` string, nullable — A unique external ID of the ingest job. You can use this to identify the ingest job in your system. ## Response `201` The created ingest job - object - `success` true, required - `data` IngestJob, required - `id` string, required — The unique ID of the ingest job. - `name` string, nullable — The name of the ingest job. - `namespaceId` string, required — The namespace ID of the ingest job. - `tenantId` string, nullable, required — The tenant ID of the ingest job. - `externalId` string, nullable, required — A unique external ID of the ingest job. You can use this to identify the ingest job in your system. - `status` 'BACKLOG' | 'QUEUED' | 'QUEUED_FOR_RESYNC' | 'QUEUED_FOR_DELETE' | 'PRE_PROCESSING' | 'PROCESSING' | 'DELETING' | 'CANCELLING' | 'COMPLETED' | 'FAILED' | 'CANCELLED', required — The status of the ingest job. - `error` string, nullable, required — The error message of the ingest job. Only exists when the status is failed. - `payload` union, required — The ingest job payload. - object - `type` 'TEXT', required - `fileName` string, nullable — The name of the file. - `text` string, required — The text to ingest. - object - `type` 'FILE', required - `fileUrl` string, uri, required — The URL of the file to ingest. - `fileName` string, nullable — The name of the file. - object - `type` 'MANAGED_FILE', required - `key` string, required — The key of the managed file to ingest. - `fileName` string, nullable — The name of the file. - object - `type` 'CRAWL', required - `url` string, uri, required — The starting URL to crawl. - `maxDepth` integer — Maximum depth to follow links from the starting URL. Depth 1 means only the initial page. Defaults to `5`. - `limit` integer — Maximum number of pages to crawl before stopping. Helps bound large sites. Defaults to `50`. - `includePaths` string[] — Only crawl URLs whose path matches at least one of these prefixes. - `excludePaths` string[] — Never crawl URLs whose path matches these prefixes. - `headers` object — Custom HTTP headers to send with crawl requests (for example, auth headers). - object - `type` 'YOUTUBE', required - `urls` string[], required — The URLs of videos, channels, or playlists (hostname must be www.youtube.com or youtu.be). - `transcriptLanguages` LanguageCode[] — We will try to fetch the first available transcript in the given languages. Default is `en`. - `includeMetadata` boolean — Whether to include metadata in the ingestion (like video description, tags, category, duration, etc...). Defaults to `false`. - object - `type` 'BATCH', required - `items` union[], required — The items to ingest. - union - object - … - object - … - object - … - `config` IngestJobConfigOutput, required — The ingest job config. - `chunkSize` integer — Chunk size (in characters). Controls approximately how much text is included in each chunk. Defaults to `2048`. - `delimiter` string — Delimiter to use for separating text before chunking. - `metadata` object — Custom metadata to be added to the ingested documents. It cannot contain nested objects; only string, number, boolean, and array of strings are allowed. - `languageCode` 'af' | 'am' | 'ar' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'en' | 'es' | 'et' | 'fa' | 'fi' | 'fr' | 'ga' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'is' | 'it' | 'jp' | 'kr' | 'lt' | 'lv' | 'mk' | 'ms' | 'mt' | 'ne' | 'nl' | 'no' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'sw' | 'ta' | 'te' | 'th' | 'tl' | 'tr' | 'uk' | 'ur' | 'vi' | 'zh' | 'zu' - `mode` 'fast' | 'balanced' | 'accurate' — Processing mode for the parser. `fast` favors speed, `accurate` (pro subscription only) favors quality and layout fidelity, and `balanced` offers a compromise between the two. Defaults to `balanced`. - `disableImageExtraction` boolean — Disable image extraction from the document. When combined with `useLlm`, images may still be automatically captioned by the partition API. Defaults to `false`. - `disableImageCaptions` boolean — Disable synthetic image captions/descriptions in output. Images will be rendered as plain img tags without alt text. Defaults to `false`. - `chartUnderstanding` boolean — Enable chart understanding. This will extract the data from the charts in the document. Defaults to `false`. - `keepPageheaderInOutput` boolean — Keep the page header in the output. Defaults to `false`. - `keepPagefooterInOutput` boolean — Keep the page footer in the output. Defaults to `false`. - `forceOcr` boolean — Force OCR on the document even if selectable text exists. Useful for scanned documents with unreliable embedded text. Defaults to `false`. - `disableOcrMath` boolean — Disable inline math recognition in OCR. This can be useful if the document contains content that is frequently misclassified as math. Defaults to `false`. - `useLlm` boolean — Enable LLM-assisted parsing to improve tables, forms, inline math, and layout detection. May increase latency and token usage. Defaults to `true`. - `chunkOverlap` number — [Deprecated] Custom chunk overlap (in characters) between consecutive chunks. Helps preserve context across chunk boundaries. - `maxChunkSize` number — [Deprecated] Hard chunk size. This option is ignored by the current partition pipeline and kept only for backwards compatibility. - `chunkingStrategy` 'basic' | 'by_title' — [Deprecated] The legacy chunking strategy. This option is ignored by the current partition pipeline and kept only for backwards compatibility. - `strategy` 'auto' | 'fast' | 'hi_res' | 'ocr_only' — [Deprecated] Legacy processing strategy used by the previous partition API. This option is ignored by the current pipeline and kept only for backwards compatibility. - `createdAt` string, required — The date and time the namespace was created. - `queuedAt` string, nullable, required — The date and time the ingest job was queued. - `preProcessingAt` string, nullable, required — The date and time the ingest job was pre-processed. - `processingAt` string, nullable, required — The date and time the ingest job was processed. - `completedAt` string, nullable, required — The date and time the ingest job was completed. - `failedAt` string, nullable, required — The date and time the ingest job failed. ## Other responses - `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). - `401` — Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. - `403` — The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. - `404` — The server cannot find the requested resource. - `409` — This response is sent when a request conflicts with the current state of the server. - `410` — This response is sent when the requested content has been permanently deleted from server, with no forwarding address. - `422` — The request was well-formed but was unable to be followed due to semantic errors. - `429` — The user has sent too many requests in a given amount of time ("rate limiting") - `500` — The server has encountered a situation it does not know how to handle. --- [API](https://skmtc.dev/agentset/apis/agentsetapi.md) · [All operations](https://skmtc.dev/agentset/apis/agentsetapi/llms.txt) · [OpenAPI document](https://skmtc.dev/agentset/apis/agentsetapi/revisions/cc6ac802092e?raw)