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.py

PYTHON

from memoair import MemoAir
 
client = MemoAir()
 
# Upload a PDF
job = client.documents.upload(
    file="company_handbook.pdf",
    group_id="org:acme",
)
 
print(f"Job ID: {job.job_id}")
print(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

PYTHON

status = client.documents.get_status(job_id="job-123")
 
print(f"Status: {status.status}")
print(f"Progress: {status.progress}%")
 
if status.is_complete():
    if status.is_success():
        print(f"Created {status.episode_count} chunks")
    else:
        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.py

PYTHON

from memoair import MemoAir
 
client = MemoAir()
 
# Upload and wait for completion
job = client.documents.upload(
    file="handbook.pdf",
    group_id="org:acme",
)
 
# Block until done (with timeout)
try:
    status = client.documents.wait_for_completion(
        job_id=job.job_id,
        timeout=300,  # 5 minutes max
    )
 
    if status.is_success():
        print(f"Document processed: {status.episode_count} chunks")
    else:
        print(f"Processing failed: {status.error_message}")
 
except TimeoutError:
    print("Document processing timed out")

GETclient.documents.list_jobs()

HTTP:GET /v1/documents/jobs

List all document processing jobs, optionally filtered by status.

PYTHON

# List all jobs
jobs = client.documents.list_jobs(limit=20)
 
# Filter by status
processing = client.documents.list_jobs(status="PARSING")
completed = client.documents.list_jobs(status="COMPLETE")
 
for job in jobs.jobs:
    print(f"{job.filename}: {job.status}")

GETclient.documents.history()

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

List all processed documents for a group.

PYTHON

# Get document history for an organization
docs = client.documents.history(
    group_id="org:acme",
    limit=50,
)
 
print(f"Total documents: {docs.total}")
for doc in docs.documents:
    print(f"- {doc.filename} ({doc.created_at})")