Documents

The Documents resource handles file upload and processing. Upload PDFs, text files, and other documents to extract knowledge and add it to your graph.

POSTclient.documents.upload()

HTTP:POST /v1/documents/upload

Upload a document for processing. Returns a job ID to track progress.

Parameters

filestr | Path | bytes | BinaryIORequired

The file to upload. Can be a file path, bytes, or file-like object.

group_idstrRequired

The group ID to associate the document with.

filenamestrOptional

Override filename (useful when passing bytes or file objects).

Returns

UploadDocumentResponse with job_id, filename, status, and message.

Example

upload_document.pypython

1from memoair import MemoAir
2
3client = MemoAir()
4
5# Upload a PDF
6job = client.documents.upload(
7    file="company_handbook.pdf",
8    group_id="org:acme",
9)
10
11print(f"Job ID: {job.job_id}")
12print(f"Status: {job.status}")

GETclient.documents.get_status()

HTTP:GET /v1/documents/jobs/{job_id}

Check the processing status of an uploaded document.

Returns

JobStatusResponse with:

job_id, filename
status: JobStatus - Current processing stage
progress: int - Percentage complete (0-100)
episode_count - Number of chunks created
is_complete(), is_success() - Helper methods

Job Status Values

QUEUEDWaiting to be processed

PARSINGExtracting text from document

ENRICHINGExtracting facts and entities

INGESTINGAdding to knowledge graph

COMPLETESuccessfully processed

ERRORProcessing failed

1status = client.documents.get_status(job_id="job-123")
2
3print(f"Status: {status.status}")
4print(f"Progress: {status.progress}%")
5
6if status.is_complete():
7    if status.is_success():
8        print(f"Created {status.episode_count} chunks")
9    else:
10        print(f"Error: {status.error_message}")

GETclient.documents.wait_for_completion()

HTTP:GET /v1/documents/jobs/{job_id}/wait

Block until a document finishes processing. Polls status internally.

Parameters

job_idstrRequired

The job ID returned from upload().

poll_intervalfloatOptionalDefault: 1.0

Seconds between status checks.

timeoutfloatOptional

Maximum seconds to wait. None = wait forever.

Example

wait_for_document.pypython

1from memoair import MemoAir
2
3client = MemoAir()
4
5# Upload and wait for completion
6job = client.documents.upload(
7    file="handbook.pdf",
8    group_id="org:acme",
9)
10
11# Block until done (with timeout)
12try:
13    status = client.documents.wait_for_completion(
14        job_id=job.job_id,
15        timeout=300,  # 5 minutes max
16    )
17
18    if status.is_success():
19        print(f"Document processed: {status.episode_count} chunks")
20    else:
21        print(f"Processing failed: {status.error_message}")
22
23except TimeoutError:
24    print("Document processing timed out")

GETclient.documents.list_jobs()

HTTP:GET /v1/documents/jobs

List all document processing jobs, optionally filtered by status.

1# List all jobs
2jobs = client.documents.list_jobs(limit=20)
3
4# Filter by status
5processing = client.documents.list_jobs(status="PARSING")
6completed = client.documents.list_jobs(status="COMPLETE")
7
8for job in jobs.jobs:
9    print(f"{job.filename}: {job.status}")

GETclient.documents.history()

HTTP:GET /v1/documents/history/{group_id}

List all processed documents for a group.

1# Get document history for an organization
2docs = client.documents.history(
3    group_id="org:acme",
4    limit=50,
5)
6
7print(f"Total documents: {docs.total}")
8for doc in docs.documents:
9    print(f"- {doc.filename} ({doc.created_at})")