Documents

Documents

@toothfairyai/sdk@latest…

Document Management Module Handles document CRUD operations, file upload/download, and semantic search.

Accessed via client.documents.

Methods

Method	HTTP	Endpoint
create	POST	POST /doc/create
createFromPath	—	derived
update	POST	POST /doc/update
get	GET	GET /doc/get/{id}
delete	DELETE	DELETE /doc/delete/{id}
list	GET	GET /doc/list
search	POST	POST /searcher
upload	—	derived
uploadFromBase64	—	derived
download	—	derived

create

Create a new document

async create(documentData: DocumentCreateData)

Endpoint: POST /doc/create · API service

Request fields

Field	Type	Required	Description
workspaceid	string	yes	Unique workspace identifier in UUID v4 format
userid	string	yes	User ID creating the document
data	array<object>	yes	Array of document records to ingest. Each element is a field mapping for one document row; the shape depends on the document type.

Response fields

Field	Type	Description
id	integer	Unique identifier for the document
document	array<object>	Document data structure for NLP documents
workspaceid	string	Unique workspace identifier in UUID v4 format
trainingdata	object	Training data for machine learning models
insertionat	string	Document creation timestamp
updatedat	string	Document last update timestamp
createdby	string	User ID who created the document
updatedby	string	User ID who last updated the document
topics	array<string>	Associated topic IDs
type	string	Document type classification

Allowed: nlpTraining, readComprehensionTraining, readComprehensionContent, questionAnswering, generativeTraining, readComprehensionPdf, readComprehensionFile, readComprehensionUrl | | rawtext | string | Raw text content of the document | | istrained | boolean | Whether the document has been trained | | source | string | Document source or origin | | title | string | Document title | | folderid | string | Parent folder identifier | | scope | string | Document scope for training purposes

Allowed: training, validation | | status | string | Document publication status

Allowed: draft, published, archived, suspended | | external_path | string | External file path or URL | | siteid | string | Associated site identifier | | hash | string | Document hash for validation | | tokens | integer | Number of tokens in the document | | completion_percentage | integer | Processing completion percentage |

Example

const result = await client.documents.create(…);

createFromPath

Create a document from a file path or URL

async createFromPath(
    filePath: string,
    userId: string,
    options: {
      title?: string;
      folderId?: string;
      topics?: string[];
      status?: string;
      scope?: string;
    } = {}
)

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

const result = await client.documents.createFromPath('…', 'agent-id');

update

Update an existing document

async update(documentId: string, userId: string, fields: DocumentUpdateData)

Endpoint: POST /doc/update · API service

Request fields

Field	Type	Required	Description
fields	object	yes	Document fields to update, as a key–value mapping of field name to new value.

Response

Returns the Document object — fields documented in the create section above.

Example

const result = await client.documents.update('agent-id', 'agent-id', …);

get

Get a document by ID

async get(documentId: string)

Endpoint: GET /doc/get/{id} · API service

Response

Returns the Document object — fields documented in the create section above.

Example

const result = await client.documents.get('agent-id');

delete

Delete a document

async delete(documentId: string): Promise<

Endpoint: DELETE /doc/delete/{id} · API service

Response fields

Field	Type	Description
success	boolean	Operation success status
data	object	Response data
message	string	Optional success message

Example

const result = await client.documents.delete('agent-id');

list

List documents in the workspace

async list(
    options: {
    limit?: number;
    pageLimit?: number;
    page?: number;
    folderId?: string;
    status?: string;
  } = {}
)

Endpoint: GET /doc/list · API service

Example

const result = await client.documents.list();

search

Search documents using semantic search

async search(
    text: string,
    options: {
      topK?: number;
      metadata?: Record<string, any>;
    } = {}
)

Endpoint: POST /searcher · AI service

Request fields

Field	Type	Required	Description
workspaceid	string	yes	Unique workspace identifier
text	string	no	Search query for knowledge hub documents. Optional if a precomputed embedding vector is supplied; when both are present the text is ignored for vector generation.
embedding	array<number>	no	Precomputed embedding vector (flat numeric array). Conditionally required when text is absent; the handler searches using this vector directly. When text is present, embedding is optional and ignored for vector generation.
topK	integer	no	Number of documents to retrieve (backend default 5).
metadata	object	no	Optional metadata filters for advanced document search. Supports filtering by document status, specific document IDs, and topic arrays.

Response fields

Returns an array of SearchResponse; fields of each element:

Field	Type	Description
id	string	Document unique identifier
score	number	Document relevance score (0.0 to 1.0)
metadata	object	Document metadata and content

Example

const result = await client.documents.search('…');

upload

Upload a file to ToothFairy

async upload(filePath: string, options: FileUploadOptions = {})

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

const result = await client.documents.upload('…');

uploadFromBase64

Upload a file from base64 string to ToothFairy

async uploadFromBase64(base64Data: string, options: Base64FileUploadOptions)

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

const result = await client.documents.uploadFromBase64('…', …);

download

Download a file from ToothFairy

async download(
    filename: string,
    outputPath: string,
    options: FileDownloadOptions = {}
)

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

const result = await client.documents.download('…', '…');