# 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`)

```json
{
    "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._