API Guide

API Guide

The FastAPI layer is the programmatic one-shot generation interface.

Use the API when you want to integrate UACRAgent into:

• scripts
• automation
• another local application
• a local service workflow

Important Scope

The current API is intended for:

• local use
• trusted callers
• same-machine workflows

It is not intended for public or multi-user deployment in its current form.

Start the API Server

uvicorn uacragent.api.main:app --reload

Configuration Source

The API currently reads .env from the server process working directory.

It does not use the desktop and CLI <app_data_dir>/.env lookup order.

API Workspace Behavior

API working files are stored under:

• <app_data_dir>/api_run/<workspace_id>/

Inside that workspace, the app keeps its own files under:

• <workspace>/.uacragent/

That bundle contains things such as:

• copied uploads when enabled
• Chroma vector database
• generated outputs

Endpoints

• GET /health
• POST /review

Request Rules

The POST /review endpoint expects:

• classified_files
• course_name
• task_type
• optional course and exam metadata
• optional effort_level
• optional reasoning_mode
• optional workspace_id
• optional copy_to_workspace

File Path Rules

Every file path in classified_files must:

• be absolute
• point to an existing regular file
• resolve under UACRAGENT_ALLOWED_BASE_DIR if that variable is set

Security Boundary

If UACRAGENT_ALLOWED_BASE_DIR is not set:

• the API accepts any absolute existing file path on the host machine

If UACRAGENT_ALLOWED_BASE_DIR is set:

• all request file paths must resolve under that directory tree

This is why the current API is documented as local trusted use only.

Request Example

{
  "classified_files": {
    "syllabus": ["C:/course/syllabus.pdf"],
    "lecture_note": ["C:/course/notes.pdf"],
    "past_exam": ["C:/course/exam1.pdf"]
  },
  "course_name": "Introduction to Algorithms",
  "exam_format": "written",
  "exam_type": "final",
  "task_type": "review_summary",
  "extra_instructions": "",
  "effort_level": "medium",
  "reasoning_mode": "quick",
  "workspace_id": "default",
  "copy_to_workspace": true,
  "university_name": "University of Toronto",
  "major": "Computer Science",
  "course_code": "CSC263",
  "professor_name": "Dr. Smith",
  "semester": "Fall 2024",
  "exam_duration": "2 hours",
  "exam_info": "Closed book. One formula sheet allowed."
}

Response Behavior

The API response includes:

• plan
• markdown_path

markdown_path is the absolute local file path to the generated Markdown file on the same machine running the API server.

In the current local-only design, that is intended for trusted local callers that can open the returned file directly.

copy_to_workspace

copy_to_workspace controls whether source files are copied into:

• <workspace>/.uacragent/uploads/

Recommended default:

• keep it at true

That gives you a more self-contained workspace.

Effort and Reasoning Controls

The API exposes both depth controls:

• effort_level
• reasoning_mode

effort_level controls retrieval and context depth.

reasoning_mode controls the generation pipeline depth.

Supported values:

• effort_level: low, medium, high
• reasoning_mode: quick, deep

Health Check

Use:

curl http://127.0.0.1:8000/health

Expected response:

{"status": "ok"}

Example curl Request

curl -X POST http://127.0.0.1:8000/review \
  -H "Content-Type: application/json" \
  -d @request.json

Best Practices

• keep the API bound to localhost only
• set UACRAGENT_ALLOWED_BASE_DIR if you want an extra local file-access boundary
• keep copy_to_workspace enabled unless you have a specific reason not to
• treat markdown_path as a local host path, not a portable artifact URL

Related Pages

• Getting Started
• CLI Guide
• Workspaces and Data
• Privacy and Disclaimer
• Troubleshooting