Atlas Librarian API Specification (v0.1.0)

This document outlines the endpoints provided by the Atlas Librarian API Gateway.

Base URL: /v1

Authentication

Currently, no authentication is required.

Tasks

Long-running operations like crawling and downloading are handled via background tasks. You initiate a task via a POST request and then poll the status endpoint using the returned task_id.

Task Object (`TaskInfo`)

{
    "task_id": "string (uuid)",
    "name": "string | null (e.g., 'crawl', 'download')",
    "state": "string (queued | running | success | error)",
    "progress": "number | null (0.0 to 1.0, only present while running)",
    "detail": "string | null (details about state, especially errors)",
    "download_links": "array[string] | null (only for successful download tasks)"
}

Endpoints

Crawler

Tags: Crawler

POST /v1/crawl
- Summary: Start Course Crawl
- Description: Initiates a background task to crawl Moodle course information. no_cache=true forces a fresh crawl.
- Request Body: CrawlRequest
```
```json
  {
      "no_cache": "boolean (optional, default: false)"
  }
```
```
- Response (202 Accepted): TaskInfo (initial state: queued)
GET /v1/crawl/status/{task_id}
- Summary: Get Crawl Task Status
- Description: Retrieves the current status (queued, running, success, error) and progress of a specific crawl task.
- Path Parameter: task_id (string)
- Response (200 OK): TaskInfo
- Response (404 Not Found): If task_id does not exist.

Downloader

Tags: Downloader

POST /v1/download
- Summary: Start Course Material Download
- Description: Initiates a background task to download materials for the specified list of courses.
- Request Body: DownloadRequest
```
```json
  {
      "courses": [
          {
              "module_id": "string",
              "term_id": "string"
          }
      ]
  }
```
```
- Response (202 Accepted): TaskInfo (initial state: queued)
- Response (400 Bad Request): If courses list is empty.
GET /v1/download/status/{task_id}
- Summary: Get Download Task Status
- Description: Retrieves the current status (queued, running, success, error) and progress of a specific download task. Includes download_links on success.
- Path Parameter: task_id (string)
- Response (200 OK): TaskInfo
- Response (404 Not Found): If task_id does not exist.

Metadata

Tags: Metadata

GET /v1/terms
- Summary: Get All Terms
- Description: Retrieves a list of all available academic terms (e.g., 'HS24', 'FS25').
- Response (200 OK): List[string]
```
```json
  ["HS24", "FS25"]
```
```

Summaries

Tags: Summaries

GET /v1/summaries/{term_id}/{course_id}
- Summary: Get Course Summary
- Description: Retrieves the generated summary content (in Markdown format) for a specific course within a specific term.
- Path Parameters: term_id (string), course_id (string)
- Response (200 OK): SummaryResponse
```
```json
  {
      "summary": "string (Markdown)"
  }
```
```
- Response (404 Not Found): If the summary for the given course/term does not exist.

Generated based on FastAPI application structure.

3.4 KiB Raw Blame History