> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # create > Upload a new document. [ref-datasphere]: /docs/server-sdks/reference/typescript/rest/datasphere Upload a new document to the [Datasphere][ref-datasphere]. ### Schema ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /api/datasphere/documents: post: operationId: subpackageDocuments_create_document summary: Create document description: >- Ingests a document from the supplied URL, applies the selected chunking strategy, and creates its Datasphere record. Use it when adding source material for later semantic retrieval; use [Search documents](/docs/apis/rest/documents/search-documents) after ingestion, or [List documents](/docs/apis/rest/documents/list-documents) to monitor processing status. #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _DataSphere_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space). tags: - subpackage_documents responses: '201': description: >- The request has succeeded and a new resource has been created as a result. content: application/json: schema: $ref: '#/components/schemas/Datasphere.Document' '400': description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode400' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' '422': description: The request contains invalid parameters. See errors for details. content: application/json: schema: $ref: '#/components/schemas/Datasphere.CreateStatusCode422' '500': description: An internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' requestBody: content: application/json: schema: $ref: '#/components/schemas/Datasphere.DocumentCreateRequest' tags: - name: subpackage_documents servers: - url: https://%7BYour_Space_Name%7D.signalwire.com description: SignalWire API components: schemas: DatasphereDocumentCreateSentenceRequestChunkingStrategy: type: string enum: - sentence description: Strategy for chunking the document title: DatasphereDocumentCreateSentenceRequestChunkingStrategy Datasphere.DocumentCreateSentenceRequest: type: object properties: url: type: string format: uri description: URL of the document. tags: type: array items: type: string description: Document tags. max_sentences_per_chunk: type: integer default: 50 description: Maximum number of sentences per chunk. chunking_strategy: $ref: >- #/components/schemas/DatasphereDocumentCreateSentenceRequestChunkingStrategy description: Strategy for chunking the document split_newlines: type: boolean default: false description: |- Whether to split chunks on new lines. **Default value:** `false` required: - url title: Datasphere.DocumentCreateSentenceRequest DatasphereDocumentCreateSlidingRequestChunkingStrategy: type: string enum: - sliding description: Strategy for chunking the document title: DatasphereDocumentCreateSlidingRequestChunkingStrategy Datasphere.DocumentCreateSlidingRequest: type: object properties: url: type: string format: uri description: URL of the document. tags: type: array items: type: string description: Document tags. chunk_size: type: integer default: 50 description: Number of words per chunk. chunking_strategy: $ref: >- #/components/schemas/DatasphereDocumentCreateSlidingRequestChunkingStrategy description: Strategy for chunking the document overlap_size: type: integer default: 10 description: Amount of overlap between chunks, in number of words. required: - url title: Datasphere.DocumentCreateSlidingRequest DatasphereDocumentCreatePageRequestChunkingStrategy: type: string enum: - page description: Strategy for chunking the document title: DatasphereDocumentCreatePageRequestChunkingStrategy Datasphere.DocumentCreatePageRequest: type: object properties: url: type: string format: uri description: URL of the document. tags: type: array items: type: string description: Document tags. chunking_strategy: $ref: >- #/components/schemas/DatasphereDocumentCreatePageRequestChunkingStrategy description: Strategy for chunking the document required: - url title: Datasphere.DocumentCreatePageRequest DatasphereDocumentCreateParagraphRequestChunkingStrategy: type: string enum: - paragraph description: Strategy for chunking the document title: DatasphereDocumentCreateParagraphRequestChunkingStrategy Datasphere.DocumentCreateParagraphRequest: type: object properties: url: type: string format: uri description: URL of the document. tags: type: array items: type: string description: Document tags. chunking_strategy: $ref: >- #/components/schemas/DatasphereDocumentCreateParagraphRequestChunkingStrategy description: Strategy for chunking the document required: - url title: Datasphere.DocumentCreateParagraphRequest Datasphere.DocumentCreateRequest: oneOf: - $ref: '#/components/schemas/Datasphere.DocumentCreateSentenceRequest' - $ref: '#/components/schemas/Datasphere.DocumentCreateSlidingRequest' - $ref: '#/components/schemas/Datasphere.DocumentCreatePageRequest' - $ref: '#/components/schemas/Datasphere.DocumentCreateParagraphRequest' title: Datasphere.DocumentCreateRequest uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid Datasphere.DocumentStatus: type: string enum: - submitted - in_progress - completed - failed description: The current Status of the Document. title: Datasphere.DocumentStatus Datasphere.ChunkingStrategy: type: string enum: - sentence - paragraph - page - sliding description: Strategy to use when chunking the document. title: Datasphere.ChunkingStrategy Datasphere.Document: type: object properties: id: $ref: '#/components/schemas/uuid' description: Unique ID of the Document. filename: type: string description: Name of the Document. status: $ref: '#/components/schemas/Datasphere.DocumentStatus' description: Status of the Document. tags: type: array items: type: string description: Document tags. chunking_strategy: $ref: '#/components/schemas/Datasphere.ChunkingStrategy' description: Strategy used to chunk the document. max_sentences_per_chunk: type: - integer - 'null' description: >- Max Sentences per Chunk. Only present when chunking strategy is 'sentence', null otherwise. split_newlines: type: - boolean - 'null' description: >- Split on Newlines. Only present when chunking strategy is 'sentence', null otherwise. overlap_size: type: - integer - 'null' description: >- Overlap Size. Only present when chunking strategy is 'sliding', null otherwise. chunk_size: type: - integer - 'null' description: >- Chunk Size. Only present when chunking strategy is 'sliding', null otherwise. number_of_chunks: type: integer description: Number of Chunks in the Document. chunks_uri: type: string description: URI path to the chunks for this document. created_at: type: string format: date-time description: Document Creation Date. updated_at: type: string format: date-time description: Document Update Date. required: - id - filename - status - tags - chunking_strategy - max_sentences_per_chunk - split_newlines - overlap_size - chunk_size - number_of_chunks - chunks_uri - created_at - updated_at title: Datasphere.Document TypesStatusCodesStatusCode400Error: type: string enum: - Bad Request title: TypesStatusCodesStatusCode400Error Types.StatusCodes.StatusCode400: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode400Error' required: - error description: The request is invalid. title: Types.StatusCodes.StatusCode400 TypesStatusCodesStatusCode401Error: type: string enum: - Unauthorized title: TypesStatusCodesStatusCode401Error Types.StatusCodes.StatusCode401: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error' required: - error description: Access is unauthorized. title: Types.StatusCodes.StatusCode401 Types.StatusCodes.RestApiErrorItem: type: object properties: type: type: string description: The category of error. code: type: string description: A specific error code. message: type: string description: A description of what caused the error. attribute: type: - string - 'null' description: The request parameter that caused the error, if applicable. url: type: string description: A link to documentation about this error. required: - type - code - message - url description: Details about a specific error. title: Types.StatusCodes.RestApiErrorItem Datasphere.CreateStatusCode422: type: object properties: errors: type: array items: $ref: '#/components/schemas/Types.StatusCodes.RestApiErrorItem' description: List of validation errors. required: - errors description: The request contains invalid parameters. See errors for details. title: Datasphere.CreateStatusCode422 TypesStatusCodesStatusCode500Error: type: string enum: - Internal Server Error title: TypesStatusCodesStatusCode500Error Types.StatusCodes.StatusCode500: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error' required: - error description: An internal server error occurred. title: Types.StatusCodes.StatusCode500 ``` ## **Response Example** ### Response (201) ```json { "id": "acaa5c49-be5e-4477-bce0-48f4b23b7720", "filename": "player_list.pdf", "status": "in_progress", "tags": [ "sports", "football", "game" ], "chunking_strategy": "sentence", "max_sentences_per_chunk": 80, "split_newlines": true, "overlap_size": 10, "chunk_size": 50, "number_of_chunks": 2345, "chunks_uri": "/api/rest/datasphere/documents/acaa5c49-be5e-4477-bce0-48f4b23b7720/chunks", "created_at": "2024-05-06T12:20-12Z", "updated_at": "2024-05-06T12:20-12Z" } ``` ## **Example** ```typescript {9} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const doc = await client.datasphere.documents.create({ url: "https://filesamples.com/samples/document/txt/sample3.txt", tags: ["support", "demo"], }); console.log("Document ID:", doc.id); ``` > Upload a new document.